Development Setup

This section is for changing StarryBio itself: components, styles, configuration schema, generation scripts, or deployment behavior. If you only want to change your own profile, start with Getting Started instead.

Prerequisites and first run

• Node.js 24.x or 26.0.0+ (.node-version selects 24.x for provider builds)
• pnpm 12.3.4
• A provider account only to deploy a modified site

git clone https://github.com/nota9x/StarryBio.git
cd StarryBio
pnpm install
pnpm dev

pnpm dev runs configuration validation, generates the currently configured Simple Icons and generated assets, and starts Astro. The Astro integration watches the selected configuration module, invalidates the module graph, and performs a full reload when it changes.

Use pnpm dev for iterative work on the page. If you modify generated files, generated asset logic, configuration validation, or deployment headers, also run a fresh production build and preview. Keep public/_headers and the Vercel catch-all headers aligned:

pnpm build
pnpm preview

The commands you will use

Command	Use it for
pnpm dev	Validate, generate, and run Astro with live config reload.
pnpm validate	Validate the strict configuration and referenced local asset paths.
pnpm icons	Regenerate configured Simple Icons from the pinned package.
pnpm generate	Generate the configured OG image, QR code, and vCard.
pnpm build	Validate, generate, and write production output to dist/.
pnpm preview	Build and run a provider-neutral Astro preview.
pnpm preview:cloudflare	Build and run the output through Wrangler locally.
pnpm format / pnpm format:check	Apply or verify Prettier formatting.
pnpm lint	Run ESLint.
pnpm typecheck	Run Astro checks and TypeScript without emit.
pnpm test	Run downstream unit and integration tests.
pnpm test:unit	Run isolated Vitest unit tests.
pnpm test:integration	Build minimal and customized deployment fixtures in temporary copies.
pnpm test:e2e	Build and test the active deployment configuration in Playwright.
pnpm test:e2e:fixtures	Run deterministic Playwright checks for minimal and customized fixtures.
pnpm test:upstream	Check maintainer-only starter and repository policy.
pnpm check	Run formatting, lint, type, and unit-test checks.
pnpm release:check	Run checks, all test layers, and the production dependency audit.
pnpm deploy	Backwards-compatible Cloudflare deployment.
pnpm deploy:cloudflare	Build then deploy with Wrangler.

The development and deploy scripts use the project’s installed tools, so avoid relying on global Astro or Wrangler versions.

Local development configuration

The repository starter configuration is real input to the site and tests, not an .env replacement:

config/starrybio.config.ts

It imports StarryBioConfig and ends with satisfies StarryBioConfig. Keep that contract when adding examples or changing settings. The runtime loads it through src/config/site.ts, which validates and normalizes it before components receive it.

For a customized deployment, set the non-secret STARRYBIO_CONFIG_PATH build input to another TypeScript module with a default export. All validation, generators, Astro, and browser tests use that selected module; without it, StarryBio uses the starter configuration above.

Local source assets belong under public/; generated outputs also write there before Astro copies everything to dist/. The project ignores generated Simple Icons, og.png, qr.png, and contact.vcf. Do not hand-edit those files as source changes.

Working with Cloudflare locally

pnpm preview:cloudflare runs pnpm build && wrangler dev, serving the static dist/ directory described by wrangler.jsonc. It is useful when a browser issue might be caused by Cloudflare routing, headers, cache directives, generated outputs, or the deployed asset model rather than Astro development mode. The normal pnpm preview uses Astro so development does not select a deployment provider.

The stock project has assets.directory: "./dist" and not_found_handling: "404-page". It has no main Worker module, Cloudflare bindings, or runtime Worker types because it deploys only static assets. Do not add Worker code, D1, KV, or environment variables unless the feature you are adding truly requires them; that is an architecture change.

Before opening a pull request

Run the narrowest relevant checks during development:

pnpm check
pnpm build

For changes that affect the rendered site, also run:

pnpm test:e2e

For a release-sized change:

pnpm release:check

For visual changes, review a narrow and wide viewport, keyboard focus, external-link behavior, and reduced-motion behavior. For a new configuration property, add schema/unit coverage and update both the starter config and Configuration Reference.

Next: Architecture and Customization maps each part of the project to its source files.