A static Astro site hosted on Cloudflare Workers with static assets and Google Analytics 4.
Use the Node.js version in .node-version and the pnpm version in package.json.
npm install --global pnpm@12.4.1
pnpm install --frozen-lockfile
pnpm devRun pnpm lint to check the project, or pnpm lint:fix to apply available ESLint
and Stylelint fixes.
ESLint uses the recommended JavaScript, TypeScript, Astro, and React Hooks rules.
Stylelint checks CSS, SCSS, and Astro style blocks, including <style lang="scss">,
with the recommended SCSS rules and stylelint-config-html/astro.
Prettier handles formatting.
Knip checks for unused files, dependencies, and exports. Run it on its own with
pnpm knip. Its Astro plugin discovers routes and follows component and script
imports automatically.
knip.jsonc lists the existing disabled navigation and link-card files as a
baseline, plus the standalone CSS helper. New unused files still fail the check.
Remove each exception when its file is activated or deleted; stale configuration
hints also fail the check. The postcss-scss exception covers the parser loaded
dynamically for Astro SCSS style blocks.
The pre-commit hook formats and lints staged files. Its tasks run sequentially so
the tools can safely update the same Astro file. Both lint commands fail on warnings.
GitHub Actions runs pnpm lint for pull requests and pushes to main.
Zizmor audits the GitHub Actions workflows in a separate security check using the
Playful Programming workflow template.
For VS Code, install the ESLint and Stylelint extensions and include astro in
eslint.validate and stylelint.validate. Include scss in stylelint.validate
to check the standalone stylesheets.
Set PUBLIC_GOOGLE_ANALYTICS_ID to the GA4 web stream measurement ID at build time. The production stream is G-QPR56LYC6D.
For a local production build, copy .env.example to .env.production and fill in the ID. Development never loads analytics, and production builds without an ID omit the Google scripts. GA4's Google tag sends page views on each full-page navigation. Enable outbound-click tracking in the stream's Enhanced Measurement settings to replace Plausible's outbound-link tracking.
On Cloudflare Workers, set the ID in the production Workers Builds build variables and secrets. Leave it unset for preview builds so preview deployments don't send events to the production stream. Preview builds also run Astro in production mode. Changing the ID requires a rebuild; this is a static site, so runtime bindings in wrangler.jsonc cannot configure analytics.
See Google's tag installation and verification guide.
Connect oceanbit/oceanbit-website to the oceanbit-website Worker through Workers & Pages using Workers Builds. If prompted, authorize the Cloudflare Workers and Pages GitHub app for this repository.
| Setting | Value |
|---|---|
| Worker name | oceanbit-website |
| Production branch | main |
| Root directory | Repository root |
| Build command | pnpm run build |
| Deploy command | pnpm exec wrangler deploy |
| Preview command | pnpm exec wrangler preview |
Set PNPM_VERSION=12.4.1 in both production and preview build environments. The .node-version file pins Node.js to 26.7.0. Set PUBLIC_GOOGLE_ANALYTICS_ID=G-QPR56LYC6D in production build variables only.
The site uses Astro's static output and needs no Cloudflare adapter or Worker script. wrangler.jsonc points Workers at dist through assets.directory. Its not_found_handling: "404-page" setting serves the generated dist/404.html with a 404 status for unknown URLs.
Workers Builds runs the build and deploy commands separately. The existing npx wrangler deploy command also works with this configuration. For local validation before uploading, run pnpm build followed by pnpm exec wrangler deploy --dry-run.
Enable preview builds in Workers Builds for branch previews. Existing Workers may need the one-time switch to Worker Previews described there. Keep preview build variables separate from production analytics configuration.
Before switching hosting, verify the Worker's homepage, /contact, static assets, and an unknown URL. Associate oceanbit.dev under Settings → Domains & Routes → Add → Custom Domain in the Worker. Verify HTTPS and Google Analytics Realtime before disconnecting the old hosting project.
See Cloudflare's Astro guide, Workers Builds configuration, Pages migration guide, and custom domain documentation.
| Command | Action |
|---|---|
pnpm dev |
Start Astro's development server |
pnpm build |
Run Astro checks and build into dist/ |
pnpm preview |
Preview the Astro production build |
pnpm preview:cloudflare |
Serve the existing build with the local Workers runtime |
pnpm run deploy |
Build and deploy the production Worker using Wrangler |
pnpm format |
Format project files |
pnpm lint |
Run ESLint, Stylelint, and Knip |
pnpm lint:js |
Check JavaScript, TypeScript, React, and Astro code |
pnpm lint:styles |
Check CSS, SCSS, and Astro style blocks |
pnpm lint:fix |
Apply available ESLint and Stylelint fixes |
pnpm knip |
Check for unused files, dependencies, and exports |
For manual uploads, authenticate with pnpm exec wrangler login first. pnpm run deploy deploys the production Worker regardless of the current Git branch. Use Workers Builds preview builds for branch previews. For previews, ensure PUBLIC_GOOGLE_ANALYTICS_ID is unset in your build environment (including local .env files).