Manual Installation

If you have an existing Astro project or prefer to set up manually, follow these steps.

Choose a theme

IndiePub ships three themes — pick one before you start:

Theme	Best for
Default	Developers, IndieWeb enthusiasts — classic two-column blog layout
Byline	Writers who want a browser-based TipTap editor and `/write` dashboard
Timeline	Micro-blogging and social streams — sidebar profile, card-based feed

All themes use the same packages and D1 schema. You can switch themes later without losing content.

Configure your npm registry

@indiepub/* packages are distributed through a private registry. You need a license key before installing — see License Key for setup instructions, including CI configuration.

Create or update .npmrc at your project root:

//registry.indiepub.dev/:_authToken=indiepub_your_token_here
@indiepub:registry=https://registry.indiepub.dev/

Install packages

pnpm add @indiepub/astro @indiepub/admin
pnpm add astro-icon

Configure the integration

Edit your astro.config.mjs:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
import icon from 'astro-icon';
import { indiepub } from '@indiepub/astro';
import { indiepubAdmin } from '@indiepub/admin';

export default defineConfig({
  site: 'https://yourdomain.com',
  output: 'server',
  adapter: cloudflare({
    platformProxy: { enabled: true },
    imageService: 'cloudflare',
  }),
  vite: {
    environments: {
      ssr: {
        external: ['node:fs/promises', 'node:path', 'node:url', 'node:crypto'],
      },
    },
  },
  integrations: [
    icon(),
    indiepub({
      title: 'My Site',
      author: {
        name: 'Your Name',
        url: 'https://yourdomain.com',
      },
    }),
    indiepubAdmin(),
  ],
});

Add TypeScript types

Create or update src/env.d.ts:

/// <reference types="astro/client" />

The @indiepub/astro package automatically augments App.Locals with indiepub, so your Astro components get full type completion.

Set up Cloudflare D1 and R2

Add a wrangler.toml at your project root:

name = "my-site"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = "./dist"

[[d1_databases]]
binding = "DB"
database_name = "my-site-db"
database_id = "YOUR_D1_DATABASE_ID_HERE"
migrations_dir = "node_modules/@indiepub/db/migrations"

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-site-media"

Create the database:

npx wrangler d1 create my-site-db
# copy the database_id into wrangler.toml

Run migrations using the script defined in package.json (which calls wrangler d1 migrations apply):

pnpm db:migrate

Add this script to your package.json if it isn’t there:

{
  "scripts": {
    "db:migrate": "wrangler d1 migrations apply DB --local"
  }
}

Configure local secrets

Create .dev.vars (never commit this file):

INDIEPUB_TOKEN=your-secret-token

See @indiepub/astro → Environment variables for the full list.

Start the dev server

pnpm dev

Visit http://localhost:4321/admin/onboarding to create your author profile and finish setup.