Deploying and Updating Astro

Cloudflare

When your Astro site is deployed on Cloudflare in the same account as the CMS API, you may need the Wrangler compatibility flag global_fetch_strictly_public. Without it, a Worker calling another Worker on the same account fails with error code: 1042, which surfaces as a 404. The installer detects this but does not edit your Wrangler config. Add it yourself, keeping your existing flags:

"compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"]

If Cloudflare builds your site from Git, set PUBLIC_KENRESOFT_CMS_URL in two places, both with your CMS API origin as the value:

• as a Build variable in the Worker’s settings, because a local .env is not used by Cloudflare builds and server-side pages create their CMS client from it while the site is built
• as a runtime variable ([vars] in your Wrangler config, or the dashboard), which the /cms proxy reads first. With it, the proxy keeps working even if a build ran without the Build variable

If Cloudflare builds your site from Git, pushing or merging to the production branch (usually main) deploys the site. When a site change uses something new in the CMS, for example the account routes and their database migration, update the CMS first (pnpm run update), then merge the site. The other order puts pages live that call API routes or tables that don’t exist yet.

The site and the CMS deploy independently and can live in separate repositories. The site’s TRUSTED_PROXY_SECRET is a runtime Worker secret, set with wrangler secret put. See Same-origin proxy.

A site on a non-Cloudflare host does not need the flag. Use a Node adapter, and the generated proxy reads process.env.

Update the integration

From the Astro project root:

npx @kenresoft-cms/create astro --update

This updates the managed files, the @kenresoft-cms/astro package and the integration metadata. It does not touch your pages, layouts, components, styles or CMS, and unlike the first run it does not modify your environment files. It requires an existing .kenresoft/integration.json. If the package is installed without one, run npx @kenresoft-cms/create astro first: that adopts existing files safely.

--no-install edits only package.json, and you run the install.

Package versions

@kenresoft-cms/astro is a 0.x package, and under semantic versioning a range such as ^0.6.0 does not cross into 0.7.0. So the CLI queries the npm registry explicitly and picks the newest stable release that is at least 0.5.1 (the first version with the proxy and auth the managed files use) and whose astro peer range allows your Astro major. If the registry is unreachable, an existing install keeps its installed version, and a first install fails. If your installed version is older than 0.5.1 and cannot be upgraded, it tells you to upgrade manually.

To update the package by hand: pnpm add @kenresoft-cms/astro@latest. The CLI is the better route because it keeps the package and the managed files in step.

Conflicts

If you edited a managed file, the updater reports it and does not overwrite it:

Conflicts:
  - src/lib/kenresoft.ts

The command exits with code 2. Merge the changes yourself, or replace the file deliberately after reviewing:

npx @kenresoft-cms/create astro --update --force

What the tooling never does

The Astro CLI never rewrites your pages, layouts, components, styles or business logic, changes your CMS deployment, edits your CMS’s CORS policy, or exposes the admin API through the proxy. pnpm run update in the CMS never modifies a website.