Development Setup

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.0.0+
• pnpm 11.23.0+
• A Cloudflare 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 in astro.config.mjs watches config/starrybio.config.ts, 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 public/_headers, also run a fresh production build and preview:

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 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:unit	Run Vitest unit tests.
pnpm test:e2e	Build then run Playwright browser tests.
pnpm release:check	Run the complete local release gate, including production dependency audit.
pnpm deploy	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.

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 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 static routing, headers, cache directives, generated outputs, or the deployed asset model rather than Astro development mode.

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, then the complete release check for a release-sized change:

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm build
pnpm test:e2e

or:

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.