From 8d34dafb413d9e0b05d03837ec95d2e38129f145 Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Wed, 1 Jul 2026 19:50:56 +0200 Subject: [PATCH 1/4] docs: clarify generateSchemaOnly writes typings too, and the "Only" naming Make explicit that generateSchemaOnly() takes no arguments and, when typingsPath is set in createAgent, writes the typings in the same pass as the schema. Clarify that "Only" means "generate the files only" (no agent start, no Forest call), not "the schema only", and point to updateTypesOnFileSystem() for the typings-only case. Co-Authored-By: Claude Opus 4.8 (1M context) --- reference/agent-api/nodejs.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index c898071..c0f91c5 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -309,7 +309,11 @@ Build the schema (`.forestadmin-schema.json`) and the TypeScript typings and wri await agent.generateSchemaOnly(): Promise; ``` -It writes to the `schemaPath` (and `typingsPath`, when set) you configured in `createAgent`. Unlike `agent.start()`, it always rebuilds the schema, even when `isProduction` is `true`, and it never contacts Forest, with one exception: if you enable experimental no-code customizations, it still fetches their configuration from the Forest API, so connectivity is required in that case. +It takes no arguments: it reads `schemaPath`, `typingsPath` and `typingsMaxDepth` from the options you passed to `createAgent`. It always writes the schema to `schemaPath`, and **also writes the TypeScript typings to `typingsPath` in the same pass whenever that option is set** (if `typingsPath` is not set, only the schema is written). Unlike `agent.start()`, it always rebuilds the schema, even when `isProduction` is `true`, and it never contacts Forest, with one exception: if you enable experimental no-code customizations, it still fetches their configuration from the Forest API, so connectivity is required in that case. + + + Despite the name, `Only` means it *only generates the files* without starting the agent or sending the schema to Forest, not "the schema only". So with `typingsPath` set, a single call produces both the schema and the typings. If you want to regenerate **only** the typings, use `agent.updateTypesOnFileSystem()` (documented above) instead. + **Example:** From 644d4678f8710cab0c741080730285993c60481f Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Wed, 1 Jul 2026 19:55:12 +0200 Subject: [PATCH 2/4] docs: drop fragile 'documented above' positional reference Co-Authored-By: Claude Opus 4.8 (1M context) --- reference/agent-api/nodejs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index c0f91c5..5b75e8f 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -312,7 +312,7 @@ await agent.generateSchemaOnly(): Promise; It takes no arguments: it reads `schemaPath`, `typingsPath` and `typingsMaxDepth` from the options you passed to `createAgent`. It always writes the schema to `schemaPath`, and **also writes the TypeScript typings to `typingsPath` in the same pass whenever that option is set** (if `typingsPath` is not set, only the schema is written). Unlike `agent.start()`, it always rebuilds the schema, even when `isProduction` is `true`, and it never contacts Forest, with one exception: if you enable experimental no-code customizations, it still fetches their configuration from the Forest API, so connectivity is required in that case. - Despite the name, `Only` means it *only generates the files* without starting the agent or sending the schema to Forest, not "the schema only". So with `typingsPath` set, a single call produces both the schema and the typings. If you want to regenerate **only** the typings, use `agent.updateTypesOnFileSystem()` (documented above) instead. + Despite the name, `Only` means it *only generates the files* without starting the agent or sending the schema to Forest, not "the schema only". So with `typingsPath` set, a single call produces both the schema and the typings. If you want to regenerate **only** the typings, use `agent.updateTypesOnFileSystem()` instead. **Example:** From 0e88fbe51d84f787f968477ba3dbd4afb9026985 Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Wed, 1 Jul 2026 19:56:57 +0200 Subject: [PATCH 3/4] docs: note typings handling in the CI schema drift-check generateSchemaOnly() also rewrites the typings when typingsPath is set. Tell CI authors to diff the typings too when committed (so a stale one fails the build), and to leave it out otherwise so a regenerated local copy doesn't break CI. Co-Authored-By: Claude Opus 4.8 (1M context) --- get-started/deploy.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/get-started/deploy.mdx b/get-started/deploy.mdx index 9ee9012..8d10a57 100644 --- a/get-started/deploy.mdx +++ b/get-started/deploy.mdx @@ -71,6 +71,8 @@ Because the file is generated locally, someone can change a data source or custo git diff --exit-code .forestadmin-schema.json ``` + If `typingsPath` is set, `generateSchemaOnly()` also rewrites the typings file. Add it to the diff when you commit it (`git diff --exit-code .forestadmin-schema.json typings.ts`) so a stale one fails CI too; if you don't commit the typings, leave them out of the diff so a regenerated local copy doesn't break the build. + Your CI job needs the same environment variables as your back-end (`FOREST_ENV_SECRET`, `FOREST_AUTH_SECRET`, `DATABASE_URL`): `createAgent` requires the secrets even though generation is offline by default. Experimental no-code customizations also fetch their configuration from Forest, which requires connectivity. From 44d31ce4bbff8c443686bbab7cf0260264bbeaeb Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Wed, 1 Jul 2026 21:16:23 +0200 Subject: [PATCH 4/4] docs: trim redundant typings restatements in generateSchemaOnly Co-Authored-By: Claude Opus 4.8 (1M context) --- reference/agent-api/nodejs.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index 5b75e8f..b9c12dd 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -309,10 +309,10 @@ Build the schema (`.forestadmin-schema.json`) and the TypeScript typings and wri await agent.generateSchemaOnly(): Promise; ``` -It takes no arguments: it reads `schemaPath`, `typingsPath` and `typingsMaxDepth` from the options you passed to `createAgent`. It always writes the schema to `schemaPath`, and **also writes the TypeScript typings to `typingsPath` in the same pass whenever that option is set** (if `typingsPath` is not set, only the schema is written). Unlike `agent.start()`, it always rebuilds the schema, even when `isProduction` is `true`, and it never contacts Forest, with one exception: if you enable experimental no-code customizations, it still fetches their configuration from the Forest API, so connectivity is required in that case. +It takes no arguments: it reads `schemaPath`, `typingsPath` and `typingsMaxDepth` from the options you passed to `createAgent`. It always writes the schema to `schemaPath`, and **also writes the TypeScript typings to `typingsPath` in the same pass whenever that option is set**. Unlike `agent.start()`, it always rebuilds the schema, even when `isProduction` is `true`, and it never contacts Forest, with one exception: if you enable experimental no-code customizations, it still fetches their configuration from the Forest API, so connectivity is required in that case. - Despite the name, `Only` means it *only generates the files* without starting the agent or sending the schema to Forest, not "the schema only". So with `typingsPath` set, a single call produces both the schema and the typings. If you want to regenerate **only** the typings, use `agent.updateTypesOnFileSystem()` instead. + Despite the name, `Only` means it *only generates the files* without starting the agent or sending the schema to Forest, not "the schema only". If you want to regenerate **only** the typings, use `agent.updateTypesOnFileSystem()` instead. **Example:**