@picked/client 0.0.72-next.1 → 0.0.72-next.3

package/dist/docs/reference/tools/vite-plugin.md

@@ -6,8 +6,8 @@ layout: docs
 # Vite Plugin
 
 `@picked/vite-plugin-picked` adds Picked to your Vite project. It reads the options
-of your project at build time. It then injects them through the Vite `define`
-option, so the SDK makes no API request at runtime. In development it also serves a
+of your project at build time. It then puts them in a module that gives them to the
+SDK, so the SDK makes no API request at runtime. In development it also serves a
 launcher page. On that page you can see a preview of an experience with your own
 feature flag values.
 
@@ -19,11 +19,75 @@ When Vite starts, in both `dev` and `build`, the plugin does this:
 
 1. It reads the configuration of your project from the Picked API.
 2. It embeds those options in your bundle.
-3. The SDK reads the embedded configuration at runtime and makes no network request.
+3. The module gives the options to the SDK as the browser loads it.
+4. The SDK reads the embedded configuration at runtime and makes no network request.
+
+Step 3 is a function call. The module gives the options to the SDK as it loads, and does
+not wait for the SDK to ask.
 
 When a preview token is there at runtime, the SDK ignores the embedded configuration and
 reads fresh data from the API.
 
+### Preload of the data file
+
+Vite puts the options of your project in their own JavaScript file. For each HTML page
+in your build, the plugin adds a `<link rel="modulepreload">` for that file. The
+browser then gets it while it reads the page, and not later when the SDK starts.
+
+The CMS content of an experience stays in its own file and gets no preload. The
+browser gets it only when an experience needs it.
+
+Some applications make their HTML from the code, and not from an HTML file in your
+project. React Router in server mode is one of these. Such a build has no page for the
+plugin to add the link to. Add this line to the code that runs in the browser instead:
+
+:::code-group
+
+```ts [entry.client.ts]
+import 'virtual:picked/data'
+```
+
+:::
+
+Your framework then sees the file in its own list and adds the preload for you.
+
+The line reads no value from the module. It is there for the work the module does as it
+loads. A bundler removes a module that only declares values, and removes the line with
+it. This module gives your project options to the SDK, which is work, so the bundler
+keeps both.
+
+Your application is correct without this line. The SDK gets the same data later, as it
+starts. The line moves that work earlier.
+
+### Types for the data file
+
+The plugin makes `virtual:picked/data` at build time. Because the module is not a file in
+your project, TypeScript cannot find its types. The plugin gives you a type file for the
+module. Point your project at that type file to import from the module:
+
+:::code-group
+
+```json [tsconfig.json]
+{
+  "compilerOptions": {
+    "types": ["@picked/vite-plugin-picked/client"]
+  }
+}
+```
+
+```ts [picked-data.ts]
+/// <reference types="@picked/vite-plugin-picked/client" />
+```
+
+:::
+
+Use one of the two. The `types` option applies to all files in your project. The
+`reference` comment applies to one file.
+
+The module gives three values: `projectConfig`, `experienceContent` and
+`manifestMetadata`. You do not give these values to the SDK. The module gives them to
+the SDK itself as the browser loads it.
+
 ### Dev launcher
 
 In development, the plugin serves an HTML page at `/`. On that page you can:
@@ -42,11 +106,23 @@ After the dev server starts, the launcher URL appears next to the Vite output:
 
 ## Options
 
-| Option           | Type      | Default                      | Description                                              |
-| ---------------- | --------- | ---------------------------- | -------------------------------------------------------- |
-| `projectId`      | `string`  | —                            | **Required.** The ID of your Picked project.             |
-| `apiUrl`         | `string`  | `https://api.picked.app`     | Your own API URL, for a self-hosted or local API.        |
-| `disableLauncher`| `boolean` | `false`                      | Turns the launcher page off in both dev and build output.|
+| Option           | Type                  | Default                  | Description                                               |
+| ---------------- | --------------------- | ------------------------ | --------------------------------------------------------- |
+| `projectId`      | `string`              | —                        | **Required.** The ID of your Picked project.              |
+| `apiUrl`         | `string`              | `https://api.picked.app` | Your own API URL, for a self-hosted or local API.         |
+| `disableLauncher`| `boolean`             | `false`                  | Turns the launcher page off in both dev and build output. |
+| `mode`           | `'bundle' \| 'api'`   | `'bundle'`               | Whether the build carries your project data.              |
+
+### mode
+
+`'bundle'` reads your project options at build time and puts them in your bundle.
+
+`'api'` does not read them. Your build then makes no request to the Picked API, and
+writes no `.picked` directory. The SDK reads your project options from the API at
+runtime instead. Use this when your build must not depend on the Picked API.
+
+The SDK has no equivalent option. It uses the data your build gives it, and the API when
+your build gives none.
 
 ## Build output
 
@@ -54,6 +130,12 @@ For a production build, `vite build`, the plugin writes an `index.html` file tha
 holds the launcher page. Set `disableLauncher` to stop this. The file lets you deploy
 the launcher next to your application, so that a stakeholder can see a preview.
 
+The plugin writes that file only when your build made no `index.html` of its own. An
+application that has an HTML entry keeps its own page at the root of the output.
+
+The plugin also writes a `.picked` directory next to your Vite `root`. It holds the
+options of your project and the CMS content of each experience.
+
 ## Related
 
 - [How to install the Vite plugin](/how-to/install-the-vite-plugin)

package/dist/docs/tutorials/first-api-call.md

@@ -118,7 +118,7 @@ When `requiresMfa` is `true`, you must complete the MFA challenge before you rec
 a session. See the [Authentication](/reference/management-api/authentication) guide.
 
 For a server-to-server integration, use
-[API key authentication](/reference/management-api/authentication#api-key-authentication) and not a
+[API key authentication](/how-to/authenticate-with-an-api-key) and not a
 session token.
 
 ## Make an authenticated query

package/dist/docs/tutorials/first-server-rendered-page.mdx

@@ -181,6 +181,6 @@ new content on the next request, and you deploy nothing.
 - [About server-side rendering](/explanation/why-server-side-rendering) — why the
   snapshot exists, and what it carries.
 - [Server snapshot](/reference/sdk/ssr/serialize) — every `serialize()` parameter.
-- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
+- [Models](/reference/dashboard/content/models) — every field type.
 - [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — how
   a draft stays out of the search index.