Getting Started

This guide produces a locally running StarryBio site, replaces the starter profile, and prepares one portable build for GitHub Pages, Cloudflare, Vercel, Netlify, or another static host. All normal site changes begin in config/starrybio.config.ts.

What you need

• Node.js 24.x or 26.0.0+ (.node-version selects 24.x for supported provider builds).
• pnpm 12.3.4 (pinned in package.json).
• An account with your chosen host only when you are ready to deploy.

StarryBio uses no application environment variables, database, storage bucket, or secret during a normal installation. Do not create a .env file expecting it to change site configuration; the build reads config/starrybio.config.ts instead.

Install and run the starter

1. Clone your copy of the repository and enter it.

   git clone https://github.com/nota9x/StarryBio.git
   cd StarryBio

2. Install the project’s locked dependencies.

   pnpm install

3. Start the local development server.

   pnpm dev

   This command first validates the configuration, regenerates any configured Simple Icons and generated downloads, then starts Astro. Open the local address that Astro prints in the terminal.

4. Keep that command running while you edit config/starrybio.config.ts. A saved change to that file triggers a full browser reload, so you can see configuration changes immediately.

Make the first safe changes

The supplied configuration is a complete, working example. Replace its identity and public URLs before deploying.

const config = {
  pageTitle: "Your Name — Links",
  favicon: "assets/images/default/favicon.svg",

  profile: {
    name: "Your Name",
    description: "A short description of what you do.",
    image: "assets/images/default/profile.svg",
  },

  sections: [
    {
      title: "Find me online",
      links: [
        {
          label: "GitHub",
          subtitle: "@your-name",
          url: "https://github.com/your-name",
          icon: { simpleIcon: "GitHub" },
        },
      ],
    },
  ],
} satisfies StarryBioConfig;

pageTitle, profile, and sections are required. At least one section must exist, although a section may later be hidden by its visibility settings. The configuration is strict: unknown or legacy properties make the build fail instead of being ignored.

Use Managing Content for links, copy buttons, and scheduled visibility. Use Assets and Generated Downloads before replacing image paths or enabling downloads.

Check the configuration and production build

Run these checks before publishing a content change:

pnpm validate
pnpm build
pnpm preview

• pnpm validate checks the schema and verifies that referenced local assets exist under public/.
• pnpm build repeats validation, creates configured generated files and Simple Icons, and writes the deployable site to dist/.
• pnpm preview builds and serves dist/ through Astro without selecting a deployment provider. Use pnpm preview:cloudflare when you specifically need to check Wrangler’s routing and _headers behavior.

While previewing, verify the home page, a deliberately unknown path (which should show the custom 404 page), every download you enabled, and any analytics browser request only if you are comfortable sending test traffic.

Next steps

1. Choose a theme and layout in Appearance and Branding.
2. Configure your canonical public URL and sharing metadata in SEO and Analytics.
3. Choose a host in Deployment Overview, then follow its deployment guide.

If the first command fails, start with the matching symptom in Troubleshooting.