feat: Vike CLI (vikejs#1434)

Co-authored-by: Romuald Brillout <[email protected]>
coder-society · Jan 9, 2025 · 1494e70 · 1494e70
1 parent 557bad2
commit 1494e70
Show file tree

Hide file tree

Showing 97 changed files with 722 additions and 311 deletions.
diff --git a/boilerplates/boilerplate-react-ts/package.json b/boilerplates/boilerplate-react-ts/package.json
@@ -2,7 +2,7 @@
   "scripts": {
     "dev": "npm run server:dev",
     "prod": "npm run build && npm run server:prod",
-    "build": "vite build",
+    "build": "vike build",
     "server": "node --loader ts-node/esm ./server/index.ts",
     "server:dev": "npm run server",
     "server:prod": "cross-env NODE_ENV=production npm run server"

diff --git a/boilerplates/boilerplate-react/package.json b/boilerplates/boilerplate-react/package.json
@@ -2,7 +2,7 @@
   "scripts": {
     "dev": "npm run server:dev",
     "prod": "npm run build && npm run server:prod",
-    "build": "vite build",
+    "build": "vike build",
     "server:dev": "node ./server",
     "server:prod": "cross-env NODE_ENV=production node ./server"
   },

diff --git a/boilerplates/boilerplate-vue-ts/package.json b/boilerplates/boilerplate-vue-ts/package.json
@@ -2,7 +2,7 @@
   "scripts": {
     "dev": "npm run server:dev",
     "prod": "npm run build && npm run server:prod",
-    "build": "vite build",
+    "build": "vike build",
     "server": "node --loader ts-node/esm ./server/index.ts",
     "server:dev": "npm run server",
     "server:prod": "cross-env NODE_ENV=production npm run server"

diff --git a/boilerplates/boilerplate-vue/package.json b/boilerplates/boilerplate-vue/package.json
@@ -2,7 +2,7 @@
   "scripts": {
     "dev": "npm run server:dev",
     "prod": "npm run build && npm run server:prod",
-    "build": "vite build",
+    "build": "vike build",
     "server:dev": "node ./server",
     "server:prod": "cross-env NODE_ENV=production node ./server"
   },

diff --git a/docs/components/static-host.tsx b/docs/components/static-host.tsx
@@ -40,7 +40,7 @@ function StaticHostDocStrategies({ name = 'the static host' }: { name?: string }
       </ul>
       <blockquote>
         <p>
-          The <code>$ vite build</code> command generates <code>dist/client/</code> containing all static assets.
+          The <code>$ vike build</code> command generates <code>dist/client/</code> containing all static assets.
         </p>
       </blockquote>
     </>
@@ -53,7 +53,7 @@ function StaticHostDocOutro({ baseUrlAddendum }: { baseUrlAddendum?: React.JSX.E
         {' '}
         You can try out your production build locally with{' '}
         <a href="https://vitejs.dev/guide/cli.html#vite-preview">
-          <code>$ vite preview</code>
+          <code>$ vike preview</code>
         </a>
         , or any other tool such as{' '}
         <a href="https://www.npmjs.com/package/serve">

diff --git a/docs/headings.ts b/docs/headings.ts
@@ -337,6 +337,16 @@ const headings = [
     url: '/config',
     sectionTitles: ['`+` files']
   },
+  {
+    level: 2,
+    title: 'CLI',
+    url: '/cli'
+  },
+  {
+    level: 2,
+    title: 'JavaScript API',
+    url: '/api'
+  },
   {
     level: 2,
     title: 'Error Page',

diff --git a/docs/headingsDetached.ts b/docs/headingsDetached.ts
@@ -321,6 +321,10 @@ const headingsDetached: HeadingDetachedDefinition[] = [
     title: '`useClientRouter()`',
     url: '/useClientRouter'
   },
+  {
+    title: 'CLI Migration',
+    url: '/migration/cli'
+  },
   {
     title: 'Migration `0.4`',
     url: '/migration-0.4'

diff --git a/docs/package.json b/docs/package.json
@@ -1,8 +1,8 @@
 {
   "scripts": {
-    "dev": "vite dev",
-    "build": "vite build",
-    "preview": "vite build && vite preview",
+    "dev": "vike dev",
+    "build": "vike build",
+    "preview": "vike build && vike preview",
     "typecheck": "tsc --noEmit --watch"
   },
   "dependencies": {

diff --git a/docs/pages/NODE_ENV/+Page.mdx b/docs/pages/NODE_ENV/+Page.mdx
@@ -14,7 +14,7 @@ In production (and staging):
 - Make sure `process.env.NODE_ENV` is a value different than `[undefined, 'development', 'dev', '']`.
   > Note that:
   > - Upon starting your server in production, make sure to set `process.env.NODE_ENV`. (E.g. `$ NODE_ENV='production' node server/index.js`.)
-  > - Upon building (`$ vite build`), Vite automatically sets `process.env.NODE_ENV` to `'production'`.
+  > - Upon building (`$ vike build`), Vite automatically sets `process.env.NODE_ENV` to `'production'`.
   > - Upon manually triggering pre-rendering (<Link href="/command-prerender">`$ vike prerender`</Link>), Vike automatically sets `process.env.NODE_ENV` to `'production'`.
 - If you use a server, make sure you don't add Vite's server middleware: it isn't needed in production and would unnecessarily bloat your production server.
 

diff --git a/docs/pages/add/+Page.mdx b/docs/pages/add/+Page.mdx
@@ -21,13 +21,28 @@ On a high-level, this is how you add Vike to your existing Vite app:
 
    - Example: <RepoLink path="/boilerplates/boilerplate-react/vite.config.js" />
 
-2. Either:
+1. Use Vike's CLI instead of Vite's CLI.
+   ```json5
+   // package.json
+   {
+     "scripts": {
+       "dev": "vite", // [!code --]
+       "dev": "vike dev", // [!code ++]
+       "build": "vite build", // [!code --]
+       "build": "vike build", // [!code ++]
+       "preview": "vite preview", // [!code --]
+       "preview": "vike preview", // [!code ++]
+     }
+   }
+   ```
+
+1. Either:
    - Enable pre-rendering, or
      > See <Link href="/pre-rendering" />
    - add a <Link href="/express">Express.js</Link>/<Link href="/hono">Hono</Link>/<Link href="/fastify">Fastify</Link>/<Link href="/server">...</Link> server (or add <Link href="/renderPage">Vike's server middleware</Link> if you already have one).
      > Example: <RepoLink path="/boilerplates/boilerplate-react/server/index.js" />
 
-3. Either:
+1. Either:
    - Use <UiFrameworkExtension name />, or
    - define <Link href="/onAfterRenderClient">`+onRenderClient.js`</Link> and <Link href="/onRenderHtml">`+onRenderHtml.js`</Link>.
      > Examples:
@@ -36,7 +51,7 @@ On a high-level, this is how you add Vike to your existing Vite app:
      > - <RepoLink text="React" path="/boilerplates/boilerplate-react/renderer/" />
      > - <RepoLink text="React + TypeScript" path="/boilerplates/boilerplate-react-ts/renderer/" />
 
-4. Create your first <Link href="/Page">`+Page.js`</Link> file.
+1. Create your first <Link href="/Page">`+Page.js`</Link> file.
    > Examples:
    > - <RepoLink text="Vue" path="/boilerplates/boilerplate-vue/pages/index/+Page.vue" />
    > - <RepoLink text="Vue + TypeScript" path="/boilerplates/boilerplate-vue-ts/pages/index/+Page.vue" />

diff --git a/docs/pages/api/+Page.mdx b/docs/pages/api/+Page.mdx
@@ -0,0 +1,70 @@
+import { Link } from '@brillout/docpress'
+
+```js
+import { dev, build, preview, prerender } from 'vike/api'
+
+// Same as CLI `$ vike dev`
+await dev()
+console.log('Dev server is ready')
+
+// Same as CLI `$ vike build`
+await build()
+console.log('Build is done')
+
+// Same as CLI `$ vike preview`
+await preview()
+console.log('Preview server is ready')
+
+// Same as CLI `$ vike prerender`
+await prerender()
+console.log('Pre-rendering is done')
+```
+
+## Options
+
+All API functions have the option `{ viteConfig: { /*...*/ }}`. (It's the only option.)
+
+> We generally recommend to define your Vite settings in your `vite.config.js` file instead of using the `viteConfig` option. The API automatically loads your `vite.config.js` file (just like the CLI).
+
+If you want to define Vite settings outside of your app (typically when <Link href="/build-your-own-framework">building your own framework</Link>) you can do this:
+
+```js
+import { dev } from 'vike/api'
+
+await dev({
+  viteConfig: {
+    // vite.config.js can live in node_modules/my-framework/src/vite.config.ts
+    configFile: './path/to/vite.config.js',
+    // The app's root can be somewhere completely else than vite.config.js
+    root: './path/to/app/'
+    // Some Vite settings overriding vite.config.js
+    /* ... */
+  }
+})
+console.log('Dev server is ready')
+```
+
+If you want to define your entire Vite config programmatically:
+
+```js
+import { build } from 'vike/api'
+
+await build({
+  viteConfig: {
+    // Don't load any vite.config.js
+    configFile: false,
+    // All Vite settings
+    /* ... */
+  }
+})
+console.log('Build is done')
+```
+
+See also: [Vite > JavaScript API > `InlineConfig`](https://vitejs.dev/guide/api-javascript.html#inlineconfig)
+
+
+## See also
+
+- [Vite > JavaScript API](https://vite.dev/guide/api-javascript)
+- <Link href="/cli" />
+- <Link href="/build-your-own-framework" />
diff --git a/docs/pages/build-your-own-framework/+Page.mdx b/docs/pages/build-your-own-framework/+Page.mdx
@@ -1,4 +1,4 @@
-import { Warning, Link } from '@brillout/docpress'
+import { Link } from '@brillout/docpress'
 
 Vike enables you to create your own framework tailored to your company's requirements.
 
@@ -72,3 +72,7 @@ You can achieve that by progressively applying one or more of the following step
 - Add utilities to your framework, such as error tracking or analytics.
 
 Feel free to reach out to the Vike team if you have any questions, and sponsorship is welcome for a tight-knit collaboration.
+
+## See also
+
+- <Link href="/api" />
diff --git a/docs/pages/cli/+Page.mdx b/docs/pages/cli/+Page.mdx
@@ -0,0 +1,28 @@
+import { Link } from '@brillout/docpress'
+
+Usage:
+- `$ vike dev` Start development server.
+- `$ vike build` Build for production.
+- `$ vike preview` Start preview server using production build.
+- `$ vike prerender` <Link href="/pre-rendering">Pre-render</Link> pages.
+- `$ vike -v` Print Vike's installed version.
+
+Vike's CLI doesn't have any options, instead:
+ - change your `vite.config.js` file, or
+ - use the `VITE_CONFIG` environment variable.
+
+For example:
+
+```bash
+# Set Vite's server.host setting to true
+$ VITE_CONFIG="{server:{host:true}}" vike dev
+
+# When running Vike's CLI over a package.json script
+$ VITE_CONFIG="{build:{outDir:'build'}}" npm run build
+```
+
+> You can define `VITE_CONFIG` using JavaScript-like syntax, [JSON syntax](https://json.org/example.html), or [JSON5 syntax](https://json5.org/#example). (Vike uses [JSON5](https://json5.org) to parse `VITE_CONFIG`.)
+
+## See also
+
+- <Link href="/api" />
diff --git a/docs/pages/cloudflare-workers/+Page.mdx b/docs/pages/cloudflare-workers/+Page.mdx
@@ -23,7 +23,7 @@ We recommend using [Wrangler v2](https://github.com/cloudflare/wrangler2) (the v
 
 ## vite-plugin-cloudflare
 
-You can also use [vite-plugin-cloudflare](https://github.com/Aslemammad/vite-plugin-cloudflare) which enables you to simply use `$ vite build` and `$ vite dev` to build and develop your worker code (including HMR support!).
+You can also use [vite-plugin-cloudflare](https://github.com/Aslemammad/vite-plugin-cloudflare) which enables you to simply use `$ vike build` and `$ vike dev` to build and develop your worker code (including HMR support!).
 
 Example: [GitHub > `Aslemammad/vite-plugin-cloudflare` > `examples/vite-plugin-ssr/`](https://github.com/Aslemammad/vite-plugin-cloudflare/tree/main/examples/vite-plugin-ssr).
 

diff --git a/docs/pages/disableAutoFullBuild/+Page.mdx b/docs/pages/disableAutoFullBuild/+Page.mdx
@@ -1,7 +1,13 @@
-import { Link } from '@brillout/docpress'
+import { Link, Warning } from '@brillout/docpress'
 
 Disable the automatic chaining of build steps.
 
+<Warning>
+  This setting is deprecated and will soon be removed. (Because Vite will soon use one Rolldown build in replacement of two Rollup builds.)
+
+  Consider <Link href="/prerender#disableautorun" /> instead.
+</Warning>
+
 ```js
 // vite.config.js
 
@@ -19,15 +25,15 @@ export default {
 }
 ```
 
-Running `$ vite build` executes three build steps:
+Running `$ vike build` executes three build steps:
  1. Client-side build (`dist/client/`).
  1. Server-side build (`dist/server/`).
  1. Pre-rendering (if <Link text="pre-rendering is enabled" href="/pre-rendering" />).
 
 When setting `disableAutoFullBuild` to `true` then only step `1` is executed. To run the full build, you then have to:
 
- - Run `$ vite build`, to build the client-side (`dist/client/`).
- - Run `$ vite build --ssr`, to build the server-side (`dist/server/`).
+ - Run `$ vike build`, to build the client-side (`dist/client/`).
+ - Run `$ vike build --ssr`, to build the server-side (`dist/server/`).
  - Run the pre-rendering programmatically, see <Link href="/prerender-programmatic" />.
 
 > If your goal is only to <Link href="/prerender-programmatic">programmatically run pre-rendering</Link> then consider using <Link href="/prerender#disableautorun"><code>prerender.disableAutoRun</code></Link> instead.

diff --git a/docs/pages/docker/+Page.mdx b/docs/pages/docker/+Page.mdx
@@ -37,10 +37,10 @@ Check whether your Docker container has enough memory, and you may also need to
 // package.json
 {
   "scripts": {
-    "build": "vite build" // [!code --]
+    "build": "vike build" // [!code --]
     "// Increase Node.js memory size to 3GB": "", // [!code ++]
     "build": "NODE_OPTIONS=--max-old-space-size=3072 npm run build:vite", // [!code ++]
-    "build:vite": "vite build" // [!code ++]
+    "build:vite": "vike build" // [!code ++]
   }
 }
 ```
diff --git a/docs/pages/hapi/+Page.mdx b/docs/pages/hapi/+Page.mdx
@@ -6,7 +6,7 @@ import { CommunityNote } from '../../components'
 We recommend the following setup.
 
 In development, we use *two* servers:
- 1. We use Vite's development server (`$ vite`). (It automatically includes Vike).
+ 1. We use Vite's development server. (It automatically includes Vike's server middleware.)
  1. We use our hapi server *without* Vite nor Vike.
 
 This means that in development, Vite is responsible for serving the entire frontend, while our hapi server is responsible only for serving the backend.

diff --git a/docs/pages/migration/cli/+Page.mdx b/docs/pages/migration/cli/+Page.mdx
@@ -0,0 +1,33 @@
+import { Link } from '@brillout/docpress'
+
+Using the Vite CLI is deprecated starting from `[email protected]`.
+
+> You can still use it, but you'll see following warning and support for Vite's CLI will be completely removed in the next major release.
+> ```
+> 1:18:05 PM [vike][Warning] The Vite CLI is deprecated
+> ```
+
+Use the Vike CLI instead:
+
+```json5
+// package.json
+{
+  "scripts": {
+    "dev": "vite", // [!code --]
+    "dev": "vike dev", // [!code ++]
+    "build": "vite build", // [!code --]
+    "build": "vike build", // [!code ++]
+    "preview": "vite preview", // [!code --]
+    "preview": "vike preview", // [!code ++]
+  }
+}
+```
+
+Vike's CLI doesn't have any option: use the `VITE_CONFIG` environment variable instead, see <Link href="/cli" />.
+
+We also recommend using <Link href="/api">Vike's JavaScript API</Link> instead of [Vite's JavaScript API](https://vite.dev/guide/api-javascript), as some features in the near future will only be available when using Vike's JavaScript API.
+
+## See also
+
+- <Link href="/cli" />
+- <Link href="/api" />
diff --git a/docs/pages/onBeforePrerenderStart/+Page.mdx b/docs/pages/onBeforePrerenderStart/+Page.mdx
@@ -41,12 +41,12 @@ async function onBeforePrerenderStart() {
 > If you don't have any parameterized route,
 > then you can pre-render your app without defining any `onBeforePrerenderStart()` hook.
 
-> The `onBeforePrerenderStart()` hooks are called when you run <code>$ vite build</code> and, consequently, are never called in development.
+> The `onBeforePrerenderStart()` hooks are called when you run <code>$ vike build</code> and, consequently, are never called in development.
 
 
 ## For bulk data fetching
 
-If you have a high number of pages that are to be pre-rendered, then running the command <code>$ vite build</code> may become slow.
+If you have a high number of pages that are to be pre-rendered, then running the command <code>$ vike build</code> may become slow.
 
 You can make pre-rendering significantly faster by providing the <Link href="/pageContext">`pageContext`</Link> of pages in `onBeforePrerenderStart()` hooks.