Skip to content
KenresoftKenresoft Docs

Existing Astro Site

Run from the root of your Astro project:

Terminal window
npx @kenresoft-cms/create astro --cms-url https://your-cms-api.example.com

This connects a project you already have. It does not create a project and does not touch the CMS.

The first time, npx asks Need to install the following packages: @kenresoft-cms/create@... Ok to proceed? (y). Answer y. In CI or any non-interactive shell, use npx --yes @kenresoft-cms/create astro ... so it does not wait for input.

What it does

Section titled “What it does”
  1. Checks the directory is an Astro project on Astro 5 or newer.
  2. Looks up @kenresoft-cms/astro on the npm registry and installs the newest stable version compatible with your Astro version (see package versions), using your package manager (pnpm, npm, yarn or bun, detected from the lockfile).
  3. Writes the managed files.
  4. Adds PUBLIC_KENRESOFT_CMS_URL to .env and .env.example, only if not already set. With no --cms-url it uses http://localhost:8787 and tells you to set the real URL.
  5. Records what it wrote in .kenresoft/integration.json.
  6. Prints what it created, updated, left unchanged or skipped, and what needs manual action.

Managed files

Section titled “Managed files”
src/pages/cms/[...path].ts     same-origin proxy
src/lib/kenresoft.ts           exports cms, cmsForRequest, browserCms, KenresoftApiError
.kenresoft/integration.json    hashes of what was written

Each managed file starts with an @kenresoft-managed comment. The proxy file is generated for Cloudflare (reading TRUSTED_PROXY_SECRET from the Worker env) when @astrojs/cloudflare is a dependency, otherwise for Node (reading process.env).

Everything else (pages, layouts, components, styles, astro.config, your Wrangler config, your own .env values) is yours and is never modified. It also does not edit your CMS’s CORS_ORIGINS.

Options

Section titled “Options”
Option Effect
--cms-url <url> CMS API URL. Must be http(s)
--no-install Only edit package.json; you run the install
--update Refresh an existing integration
--force With --update, or over a conflict: replace edited managed files
--dir <path> Run against another directory
--help, -h Show help

Exit codes: 0 success, 1 error, 2 finished with conflicts.

Running it again is safe. Files that already match are kept and now tracked. A file at a managed path that differs from what would be generated is reported as a conflict and left alone.

Update later with npx @kenresoft-cms/create astro --update: see Astro deployment.

After the command runs

Section titled “After the command runs”

The command finishes with a “Needs manual action” list. It reports these and does not edit them:

Message What to do
No server adapter found Add an adapter (for example astro add cloudflare) and enable server rendering. The proxy needs on-demand rendering
.env already sets PUBLIC_KENRESOFT_CMS_URL Check the value is your CMS API origin. The installer does not overwrite it
Add global_fetch_strictly_public to compatibility_flags Edit wrangler.jsonc. Needed when the site and API share a Cloudflare account. See Astro deployment
Set the same TRUSTED_PROXY_SECRET on both sides Optional, but without it per-IP rate limits treat all visitors as one. See Same-origin proxy
List this site’s origin in CORS_ORIGINS Add it to CORS_ORIGINS in the CMS wrangler.toml and run wrangler deploy. See Authentication and CORS
Possible existing /cms handling Make sure only one thing serves /cms/*

Commit the generated files, including .kenresoft/integration.json. It only records file hashes so the updater can detect your edits, and it contains no secrets.