CHANGELOG.md

@@ -1,3 +1,32 @@
+# [2.0.0-beta.51](https://github.com/vuepress/vuepress-next/compare/v2.0.0-beta.50...v2.0.0-beta.51) (2022-08-28)
+
+
+### Bug Fixes
+
+* **bundler-vite:** do not change output entry of client bundle (close [#1043](https://github.com/vuepress/vuepress-next/issues/1043)) ([b3565cb](https://github.com/vuepress/vuepress-next/commit/b3565cba73d0e87540b563d86792bbd2bd219de0))
+* **bundler-webpack:** add extensionAlias config ([697e7ae](https://github.com/vuepress/vuepress-next/commit/697e7aef4b27e4b4743895c84860d09681ad0e29))
+* **core:** resolve app version correctly ([2a93513](https://github.com/vuepress/vuepress-next/commit/2a935136fca8980cf89146e6d6f1b0a42a50b700))
+
+
+### Features
+
+* **client:** make args of defineClientConfig optional ([e418e02](https://github.com/vuepress/vuepress-next/commit/e418e02b8c6bb179fd2aae2ce1abb9341038e2d0))
+* support layouts option in client config ([#1053](https://github.com/vuepress/vuepress-next/issues/1053)) ([a67a0bf](https://github.com/vuepress/vuepress-next/commit/a67a0bfd806bda548532836ebf8ec1704b7bcb8a))
+
+
+### Performance Improvements
+
+* reduce memory usage during rendering ([ea0a2b2](https://github.com/vuepress/vuepress-next/commit/ea0a2b213a107c7972da63dededc163c716185d6))
+
+
+### BREAKING CHANGES
+
+* theme API `layouts` has been removed, layouts should be set in client config instead of theme entry
+* `404` layout should be renamed to `NotFound` layout
+* node API `app.layouts` has been removed
+
+
+
 # [2.0.0-beta.50](https://github.com/vuepress/vuepress-next/compare/v2.0.0-beta.49...v2.0.0-beta.50) (2022-08-23)
 
 

docs/.vuepress/configs/meta.ts

@@ -3,6 +3,6 @@ import { fs } from '@vuepress/utils'
 
 const require = createRequire(import.meta.url)
 
-export const version = fs.readJSONSync(
+export const version = fs.readJsonSync(
   require.resolve('@vuepress/core/package.json')
 ).version

docs/advanced/architecture.md

@@ -6,13 +6,13 @@
 
 The above figure shows a brief overview of the VuePress architecture:
 
-- Node App will generate temp files, including the layouts, pages, routes, etc.
+- Node App will generate temp files, including the pages, routes, etc.
 - Bundler will handle Client App together with the temp files, just like a common Vue SPA.
 
 As a developer, you must be aware of that VuePress has two main parts: **Node App** and **Client App**, which is important when developing plugins and themes:
 
 - The entry file of a plugin or a theme will be loaded in Node App.
-- Client files will be loaded in Client App, which will be handled by bundler. For example, layouts, components, app setup files, app enhance files, etc.
+- Client files will be loaded in Client App, which will be handled by bundler. For example, components, client config files, etc.
 
 ## Core Process and Hooks
 

docs/advanced/cookbook/usage-of-client-config.md

@@ -20,6 +20,7 @@ import { defineClientConfig } from '@vuepress/client'
 export default defineClientConfig({
   enhance({ app, router, siteData }){},
   setup(){},
+  layouts: {},
   rootComponents: [],
 })
 ```
@@ -142,6 +143,21 @@ export default defineClientConfig({
 })
 ```
 
+## layouts
+
+The `layouts` options is to set layout components. After layout components are registered here, users can use it via [layout](../../reference/frontmatter.md#layout) frontmatter.
+
+```ts
+import { defineClientConfig } from '@vuepress/client'
+import MyLayout from './layouts/MyLayout.vue'
+
+export default defineClientConfig({
+  layouts: {
+    MyLayout,
+  },
+})
+```
+
 ## rootComponents
 
 The `rootComponents` is a components array to be placed directly into the root node of the client vue app.

docs/advanced/theme.md

@@ -14,31 +14,54 @@ import { getDirname, path } from '@vuepress/utils'
 const __dirname = getDirname(import.meta.url)
 
 const fooTheme = (options) => {
+  // returns a theme object
   return {
     name: 'vuepress-theme-foo',
-    layouts: {
-      Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
-      404: path.resolve(__dirname, 'layouts/404.vue'),
-    },
-    // ...
+
+    // path to the client config of your theme
+    clientConfigFile: path.resolve(__dirname, 'client.js'),
+
+    // set custom dev / build template
+    // if the template is not specified, the default template from `@vuepress/client` will be used
+    templateBuild: path.resolve(__dirname, 'templates/build.html'),
+    templateDev: path.resolve(__dirname, 'templates/dev.html'),
+
+    // use plugins
+    plugins: [
+      // ...
+    ],
+
+    // other plugin APIs are also available
   }
 }
 
 const barTheme = (options) => {
+  // returns a theme function
   return (app) => {
     return {
       name: 'vuepress-theme-bar',
-      layouts: {
-        Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
-        404: path.resolve(__dirname, 'layouts/404.vue'),
-      },
       // ...
     }
   }
 }
 ```
 
-The `layouts` field declares the layouts provided by your theme. A theme must provide at least two layouts: `Layout` and `404`. The former is to provide default layout for common pages, while the latter is to provide layout for 404 page.
+Then, create theme's client config file `client.js` :
+
+```ts
+import { defineClientConfig } from '@vuepress/client'
+import Layout from './layouts/Layout.vue'
+import NotFound from './layouts/NotFound.vue'
+
+export default defineClientConfig({
+  layouts: {
+    Layout,
+    NotFound,
+  },
+})
+```
+
+The `layouts` field declares the layouts provided by your theme. A theme must provide at least two layouts: `Layout` and `NotFound`. The former is to provide default layout for common pages, while the latter is to provide layout for 404-not-found page.
 
 The `Layout` layout should contain the [Content](../reference/components.md#content) component to display the markdown content:
 
@@ -50,7 +73,7 @@ The `Layout` layout should contain the [Content](../reference/components.md#cont
 </template>
 ```
 
-The `404` layout will be used for the `404.html` page:
+The `NotFound` layout will be used for the `404.html` page:
 
 ```vue
 <template>

docs/guide/migration.md

@@ -9,6 +9,7 @@ Some major changes and enhancements of VuePress v2:
 - VuePress v2 is now using Vue 3, so make sure your components and other client files are compatible with Vue 3.
 - VuePress v2 is developed with TypeScript, so it provides better TS support now. It's highly recommended to use TypeScript to develop plugins and themes. VuePress config file also supports TypeScript, and you can use `.vuepress/config.ts` directly.
 - VuePress v2 supports both Webpack and Vite as bundler. Now Vite is the default bundler, while you can still choose to use Webpack. You can even use Vite in dev mode to get better development experience, and use Webpack in build mode to get better browser compatibility.
+- VuePress v2 is now released as pure ESM packages, and CommonJS config files are no longer supported.
 
 Core ideas and processes of VuePress v2 are the same with v1, while v2 API has been re-designed and becomes more normalized. So you might encounter breaking changes when migrating an existing v1 project to v2. This guide is here to help you migrating v1 sites / plugins / themes to v2.
 
@@ -20,6 +21,20 @@ Core ideas and processes of VuePress v2 are the same with v1, while v2 API has b
 
 ### User Config Change
 
+Config file should be in ESM format, and CommonJS format config file is no longer supported.
+
+```diff
+// .vuepress/config.js
+
+- module.exports = {
+-   // user config
+- }
+
++ export default {
++   // user config
++ }
+```
+
 #### theme
 
 Using a theme via string is not supported. Import the theme directly.
@@ -311,7 +326,7 @@ Some major breaking changes:
 - There is no **conventional theme directory structure** anymore.
   - The file `theme/enhanceApp.js` will not be used as client app enhance file implicitly. You need to specify it explicitly in `clientConfigFile` hook.
   - Files in `theme/global-components/` directory will not be registered as Vue components automatically. You need to use [@vuepress/plugin-register-components](../reference/plugin/register-components.md), or register components manually in `clientConfigFile`.
-  - Files in `theme/layouts/` directory will not be registered as layout components automatically. You need to specify it explicitly in `layouts` option.
+  - Files in `theme/layouts/` directory will not be registered as layout components automatically. You need to specify it explicitly in `layouts` option in `clientConfigFile`.
   - Files in `theme/templates/` directory will not be used as dev / ssr template automatically. You need to specify theme explicitly in `templateBuild` and `templateDev` option.
   - Always provide a valid js entry file, and do not use `"main": "layouts/Layout.vue"` as the theme entry anymore.
 - `themeConfig` is removed from user config and site data. To access the `themeConfig` as you would via `this.$site.themeConfig` in v1, we now recommend using the [@vuepress/plugin-theme-data](../reference/plugin/theme-data.md) plugin and its `useThemeData` composition API.
@@ -325,9 +340,11 @@ For more detailed guide about how to write a theme in v2, see [Advanced > Writin
 
 #### layouts
 
-Now you need to specify the layouts directory or layout components manually.
+Removed.
+
+Now you need to specify layout component in the client config file of your theme.
 
-See [Theme API > layouts](../reference/theme-api.md#layouts).
+See [Advanced > Writing a theme](../advanced/theme.md).
 
 #### extend
 

docs/reference/default-theme/extending.md

@@ -22,30 +22,20 @@ Default theme's `Layout` provides some slots:
 
 With the help of them, you can add or replace content easily. Here comes an example to introduce how to extend default theme with layout slots.
 
-Firstly, create your local theme `.vuepress/theme/index.ts`:
+Firstly, create a client config file `.vuepress/client.ts`:
 
 ```ts
-import type { Theme } from '@vuepress/core'
-import { defaultTheme } from '@vuepress/theme-default'
-import type { DefaultThemeOptions } from '@vuepress/theme-default'
-import { getDirname, path } from '@vuepress/utils'
-
-const __dirname = getDirname(import.meta.url)
+import { defineClientConfig } from '@vuepress/client'
+import Layout from './layouts/Layout.vue'
 
-export const localTheme = (options: DefaultThemeOptions): Theme => {
-  return {
-    name: 'vuepress-theme-local',
-    extends: defaultTheme(options),
-    layouts: {
-      Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
-    },
-  }
-}
+export default defineClientConfig({
+  layouts: {
+    Layout,
+  },
+})
 ```
 
-Then your theme will extend default theme, and override the `Layout` layout.
-
-Next, create the `.vuepress/theme/layouts/Layout.vue`, and make use of the slots that provided by the `Layout` of default theme:
+Next, create the `.vuepress/layouts/Layout.vue`, and make use of the slots that provided by the `Layout` of default theme:
 
 ```vue
 <script setup>
@@ -67,21 +57,7 @@ import ParentLayout from '@vuepress/theme-default/layouts/Layout.vue'
 </style>
 ```
 
-Finally, remember to use your theme in the config file:
-
-```ts
-import { path } from '@vuepress/utils'
-import { defineUserConfig } from 'vuepress'
-import { localTheme } from './theme'
-
-export default defineUserConfig({
-  theme: localTheme({
-    // default theme options
-  }),
-})
-```
-
-You will add a custom footer to every normal pages in default theme (excluding homepage):
+Then the default `Layout` layout has been overridden by your own local layout, which will add a custom footer to every normal pages in default theme (excluding homepage):
 
 ![extending-a-theme](/images/cookbook/extending-a-theme-01.png)
 
@@ -91,39 +67,45 @@ The layout slots are useful, but sometimes you might find it's not flexible enou
 
 Default theme has registered [alias](../plugin-api.md#alias) for every [non-global components](https://github.com/vuepress/vuepress-next/tree/main/packages/%40vuepress/theme-default/src/client/components) with a `@theme` prefix. For example, the alias of `HomeFooter.vue` is `@theme/HomeFooter.vue`.
 
-Then, if you want to replace the `HomeFooter.vue` component, just override the alias:
+Then, if you want to replace the `HomeFooter.vue` component, just override the alias in your config file `.vuepress/config.ts`:
 
 ```ts
-import type { Theme } from '@vuepress/core'
-import { defaultTheme } from '@vuepress/theme-default'
-import type { DefaultThemeOptions } from '@vuepress/theme-default'
 import { getDirname, path } from '@vuepress/utils'
+import { defaultTheme, defineUserConfig } from 'vuepress'
 
 const __dirname = getDirname(import.meta.url)
 
-export const localTheme = (options: DefaultThemeOptions): Theme => {
-  return {
-    name: 'vuepress-theme-local',
-    extends: defaultTheme(options),
-    alias: {
-      '@theme/HomeFooter.vue': path.resolve(__dirname, './components/MyHomeFooter.vue'),
-    },
-  }
-}
+export default defineUserConfig({
+  theme: defaultTheme(),
+  alias: {
+    '@theme/HomeFooter.vue': path.resolve(__dirname, './components/MyHomeFooter.vue'),
+  },
+})
 ```
 
-In fact, you can even use components replacement without extending default theme. The [alias](../plugin-api.md#alias) option is part of [Plugin API](../plugin-api.md), so you only need to set the aliases in your config file to replace components.
+## Developing a Child Theme
+
+Instead of extending the default theme directly in `.vuepress/config.ts` and `.vuepress/client.ts`, you can also develop your own theme extending the default theme:
 
 ```ts
+import type { Theme } from '@vuepress/core'
+import { defaultTheme, type DefaultThemeOptions } from '@vuepress/theme-default'
 import { getDirname, path } from '@vuepress/utils'
-import { defaultTheme, defineUserConfig } from 'vuepress'
 
 const __dirname = getDirname(import.meta.url)
 
-export default defineUserConfig({
-  theme: defaultTheme(),
-  alias: {
-    '@theme/HomeFooter.vue': path.resolve(__dirname, './components/MyHomeFooter.vue'),
-  },
-})
+export const childTheme = (options: DefaultThemeOptions): Theme => {
+  return {
+    name: 'vuepress-theme-child',
+    extends: defaultTheme(options),
+
+    // override layouts in child theme's client config file
+    clientConfigFile: path.resolve(__dirname, './client.js'),
+
+    // override component alias
+    alias: {
+      '@theme/HomeFooter.vue': path.resolve(__dirname, './components/MyHomeFooter.vue'),
+    },
+  }
+}
 ```

docs/reference/frontmatter.md

@@ -96,8 +96,8 @@ import { defineClientConfig } from '@vuepress/client'
 import CustomLayout from './CustomLayout.vue'
 
 export default defineClientConfig({
-  enhance({ app }) {
-    app.component('CustomLayout', CustomLayout)
+  layouts: {
+    CustomLayout,
   },
 })
 ```

docs/reference/node-api.md

@@ -172,16 +172,6 @@ const dev = async () => {
 
   It is only available in and after [onInitialized](./plugin-api.md#oninitialized) hook.
 
-### layouts
-
-- Type: `Record<string, string>`
-
-- Details:
-
-  The layout components map, of which the key is the layout name, the value is the absolute file path of the layout component.
-
-  It is only available in and after [onInitialized](./plugin-api.md#oninitialized) hook.
-
 ### pages
 
 - Type: `Page[]`