PageZERO

An open-source TypeScript starter for full-stack web applications built for Cloudflare.

Guiding principles:

• Easy to learn
• Fast to build with
• Pleasure to work with
• Cheap to maintain

🔧 Prerequisites

Before getting started, make sure you have the following installed:

• Node.js: Version >= 24.6.0
• Bun: Version >= 1.2.20

Tip

For PageZERO, asdf is the recommended runtime version manager. After asdf setup, to automatically install proper asdf plugins and versions of Node.js and Bun, run in your project directory:

asdf plugin add nodejs && asdf plugin add bun && asdf install

Alternatively, if you are in a rush and have Node.js already installed, you can quickly install Bun with npm install -g bun.

⚡️ Quick start

In 4 steps:

1. bun create pagezero-dev/pagezero <your-project-name>
2. cd <your-project-name>
3. bun run setup
4. bun run dev

You should be able to access the http://localhost:3000/ development page now.

Note

bun create will:

• download the template
• execute bun install
• initialize a fresh Git repo

🧑‍💻 The stack

Building on strong foundations:

Core:

• 🚀 Vite + React + React Router v7
• ☁️ Cloudflare Workers (hosting) + Cloudflare D1 (database)
• 🏗️ TypeScript + TailwindCSS + Drizzle ORM

Tooling:

• ⚡ Bun (package manager)
• ✨ Biome (code quality)
• ✅ GitHub Actions (CI/CD)
• 🧪 Vitest + Playwright (testing)
• 📖 Shadcn + Storybook (UI)

✨ Scripts

Essential bun scripts:

• bun run setup - performs bun install, sets up basic env vars, database and Playwright browser drivers
• bun run dev - boots the development server
• bun run preview - builds the app and boots the compiled version
• bun run test - executes unit tests
• bun run test:watch - run unit tests in watch mode
• bun run test:e2e:ui - executes browser tests in UI mode, perfect for development
• bun run check - code quality check (linting and formatting)
• bun run check:types - TypeScript types check
• bun run check:fix - fix linting and formatting issues
• bun run storybook - boots Storybook
• bun run doctor - runs all basic sanity checks: format, lint, types check and unit tests

🚀 Deployment

Deployment in PageZERO happens through the GitHub Actions CI/CD pipeline. That means once the pipeline is set, every merge to the main branch will automatically trigger deployment to Cloudflare Workers and database migration for Cloudflare D1.

Additionally, every PR will trigger "preview deployment", so you can access the version of your app for every PR. More about preview urls: https://developers.cloudflare.com/workers/configuration/previews/.

The database for preview deployments is shared. If you wish to reset it, you can manually trigger the "Reset preview database" workflow in GitHub Actions.

OK, now to make it all work, we must go through a few setup steps...

Cloudflare configuration

Important

Steps below require a Cloudflare account.

1. Login through bunx wrangler login

2. Create production and preview database:

   bunx wrangler d1 create <project-name>-production
   bunx wrangler d1 create <project-name>-preview

3. Update wrangler.json with: project name, database names and returned database_ids

4. Perform manual deployments to create Cloudflare Workers:

   bun run deploy:production
   bun run deploy:preview

Github configuration

Important

Steps below require GitHub CLI. For Mac, you can set it up with: brew install gh.

1. Login through gh auth login

2. Create a GitHub repo for the project and push all changes

   cd <project-name>
   gh repo create <project-name> --private --source=. --remote=origin --push

3. Obtain Cloudflare Account ID

   bunx wrangler whoami

4. Obtain Cloudflare D1 database IDs

   bunx wrangler d1 list

5. Add the following repository variables:

   gh variable set CLOUDFLARE_ACCOUNT_ID --body "<your-cloudflare-account-id>"
   gh variable set CLOUDFLARE_DATABASE_ID_PRODUCTION --body "<your-production-database-id>"
   gh variable set CLOUDFLARE_DATABASE_ID_PREVIEW --body "<your-preview-database-id>"

   You can browse variables by going to the GitHub UI "Settings / Secrets and variables / Actions" for your repo or by executing gh variable list.

6. Obtain Cloudflare API token

   Cloudflare API token can be obtained through the Cloudflare dashboard under "Manage account / Account API Tokens". You have to create the token there. The token will require the following permissions: D1:Edit, Workers Scripts:Edit.

7. Add the following repository secret:

   gh secret set CLOUDFLARE_API_TOKEN
   gh secret set CLOUDFLARE_API_TOKEN --app dependabot

   Secret for Dependabot needs to be set separately. Otherwise Dependabot PRs will not perform preview deploys.

   You can browse secrets by going to the GitHub UI "Settings / Secrets and variables / Actions" for your repo or by executing gh secret list.

All done! 🎉

Now, you can test everything out. Create a PR in your project GitHub repository. You should notice an action in the "Actions" section being triggered. If the basic checks pass, the workflow will perform preview deployment to Cloudflare workers and database migration on your preview database. After deployment, the "View deployment" button should appear in your PR, with a link to your PR "preview" deployment.

When you merge PR to "main", production deployment will happen, and database migration will be performed on your production DB.