vite-plugin-vercel 10.0.0-beta.5 → 10.0.0

package/README.md

@@ -1,15 +1,9 @@
 # vite-plugin-vercel
 
-> [!NOTE]
-> You are on the [Vite Environment API](https://vite.dev/guide/api-environment.html#environment-configuration) beta branch (v10). Check out [v9 branch](https://github.com/magne4000/vite-plugin-vercel/tree/v9) for current stable version.
-
 Vercel adapter for [Vite](https://vitejs.dev/).
 
 Bundle your Vite application as supported by [Vercel Output API (v3)](https://vercel.com/docs/build-output-api/v3).
 
-> [!NOTE]
-> This plugin is mostly a re-export of [`@photonjs/vercel`](https://github.com/photon-js/photon/tree/main/packages/adapter-vercel)
-
 ## Install
 
 ```bash
@@ -51,32 +45,27 @@ Install this package as a dev dependency and add it to your Vite config:
 // vite.config.ts
 import { defineConfig } from 'vite';
 import vercel from 'vite-plugin-vercel';
-import { getEntriesFromFs } from "vite-plugin-vercel/utils";
-
-const entries = await getEntriesFromFs("endpoints/api", {
-  // Auto mapping examples:
-  //   endpoints/api/page.ts -> /api/page
-  //   endpoints/api/name/[name].ts -> /api/name/*
-  destination: "api",
-});
 
 export default defineConfig({
-  plugins: [vercel({
-    entries,
-  })],
+  plugins: [vercel()],
+  vercel: {
+    // optional configuration options, see "Advanced usage" below for details
+  },
 });
 ```
 
 > [!NOTE]
-> `@vercel/build` currently forces the building of files in the _/api_ folder, with no way to disable this behavior.
-> It's recommended to place your files in a different folder.
+> Files under `/api` or `/_api` directory will automatically be added under `/api/*` route
+> Prefer using `/_api` directory, as `@vercel/build` is currently force building `/api` files,
+> with no way to disable it, thus avoiding double compilation and unexpected behaviour.
 
 ### Configure endpoints
 
-Endpoints added via `getEntriesFromFs` can be configured by exporting values from the endpoint file:
+Endpoints under `/api`, `/_api` or added through `additionalEndpoints` can be configured
+by exporting values from the endpoint file:
 
 ```ts
-// file: endpoints/api/endpoint.ts
+// file: _api/endpoint.ts
 
 // Should run on edge runtime
 export const edge = true;
@@ -101,11 +90,53 @@ export default async function handler() {
 }
 ```
 
+> [!NOTE]
+> Please create an issue if you need other per-endpoints configurations
+
 ### Edge middleware
 
 You can use [Edge middleware as describe in the official documentation](https://vercel.com/docs/functions/edge-middleware/middleware-api) (i.e. with a `middleware.ts` file at the root of your project).
 
-## Advanced settings
+## Usage with Vike
+
+[Vike](https://vike.dev/) is supported through [@vite-plugin-vercel/vike](/packages/vike-integration/README.md) plugin.
+
+You only need to install `@vite-plugin-vercel/vike`, the Vite config stays the same as above.
+
+You can then leverage [config files](https://vike.dev/config) to customize your endpoints:
+
+```ts
+// /pages/product/+config.ts
+
+import Page from './Page';
+import type { Config } from 'vike/types';
+
+export default {
+  // Customize ISR config for this page
+  isr: { expiration: 15 },
+  // Target Edge instead of Serverless
+  edge: true,
+  // append headers to all responses
+  headers: {
+    'X-Header': 'value'
+  }
+} satisfies Config;
+```
+
+You will also need to extend the [renderer config](https://vike.dev/config#renderer) so that `vike` is aware of the new parameter:
+
+```ts
+// /renderer/+config.ts
+
+import config from '@vite-plugin-vercel/vike/config';
+import type { Config } from 'vike/types';
+
+export default {
+  extends: config,
+} satisfies Config;
+```
+
+## Advanced usage
 
 ```ts
 // vite.config.ts
@@ -113,7 +144,8 @@ import { defineConfig } from 'vite';
 import vercel from 'vite-plugin-vercel';
 
 export default defineConfig({
-  plugins: [vercel({
+  plugins: [vercel()],
+  vercel: {
     // All the followings optional
 
     /**
@@ -130,7 +162,14 @@ export default defineConfig({
      * Defaults to 86400 seconds (24h).
      */
     expiration: 86400,
-
+    /**
+     * Also known as Server Side Generation, or SSG.
+     * If present, this function is responsible to create static files in `.vercel/output/static`.
+     * Defaults to `false`, which disables prerendering.
+     */
+    prerender(resolvedConfig) {
+      // Check `/packages/vike/vike.ts` `prerender` for an example
+    },
     /**
      * See https://vercel.com/docs/projects/project-configuration#rewrites
      */
@@ -164,16 +203,19 @@ export default defineConfig({
      */
     trailingSlash: true,
     /**
-     * Use `getEntriesFromFs` for mapping your filesystem routes to entries.
-     * If you are interfacing this plugin with a framework, entries can also be added through the Photon API
+     * By default, all `api/*` and `_api/*` endpoints are compiled under `.vercel/output/functions/api/*.func`.
+     * If others serverless functions need to be compiled under `.vercel/output/functions`, they should be added here.
+     * For instance, a framework can leverage this to have a generic ssr endpoint
+     * without requiring the user to write any code.
      */
-    entries: {
-      root: {
-        id: 'src/routes/root.ts',
-        name: 'root',
-        route: '/'
-      }
-    },
+    additionalEndpoints: [
+      {
+        // can also be an Object representing an esbuild StdinOptions
+        source: '/path/to/file.ts',
+        // URL path of the handler, will be generated to `.vercel/output/functions/api/file.func/index.js`
+        destination: '/api/file',
+      },
+    ],
     /**
      * Advanced configuration to override .vercel/output/config.json
      * See https://vercel.com/docs/build-output-api/v3/configuration#configuration
@@ -186,31 +228,32 @@ export default defineConfig({
       // cache?: string[];
       // crons?: CronsConfig;
     },
+    /**
+     * ISR and SSG pages are mutually exclusive. If a page is found in both, ISR prevails.
+     * Keys are path relative to .vercel/output/functions directory, either without extension,
+     * or with `.prerender-config.json` extension.
+     * If you have multiple isr configurations pointing to the same underlying function, you can leverage the `symlink`
+     * property.
+     *
+     * Can be an object or a function returning an object (or a Promise of an object).
+     *
+     * Check `/packages/vike/vike.ts` `vitePluginVercelVpsIsrPlugin` for advanced usage.
+     */
+    isr: {
+      // `symlink: 'ssr_'` means that a function is available under `.vercel/output/functions/ssr_.func`
+      '/pages/a': { expiration: 15, symlink: 'ssr_', route: '^/a/.*$' },
+      '/pages/b/c': { expiration: 15, symlink: 'ssr_', route: '^/b/c/.*$' },
+      '/pages/d': { expiration: 15, symlink: 'ssr_', route: '^/d$' },
+      '/pages/e': { expiration: 25 },
+    },
     /**
      * Defaults to `.vercel/output`. Mostly useful for testing purpose
      */
     outDir: '.vercel/output',
-  })]
+  },
 });
 ```
 
-## FAQ
-
-### What does ISR do in dev mode?
-Nothing. It's a production-only feature
-
-### What does `edge: true` target do in dev mode?
-Nothing (yet?). If you have a use-case where an actual Edge runtime would be necessary in dev, please open a discussion
-
-### I don't see Vercel specific headers in dev mode
-This is not yet supported. Please open an issue if you need this (PR welcome).
-
-Related documentation: https://vercel.com/docs/edge-network/headers/request-headers
-
-## Migrations
-
-- [Migration from v9 to v10](https://github.com/magne4000/vite-plugin-vercel/blob/main/MIGRATION.md)
-
 ## Demo
 
 https://vike-photon-demo.vercel.app/