Quick Start

Prerequisites

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

• Node.js: Version 24 or higher
• Bun: Version 1.3 or higher

If you’re not sure how to install Node.js or Bun, check out the Node and Bun setup section.

1. Initialize a new PageZERO project:

   Open-source edition

   bunx pagezero@latest init

   Paid edition

   bunx pagezero@latest init --powerup

   Get PowerUP Learn more

2. Navigate to your project directory:

   cd <your-project-name>

3. Start the development server:

   bun dev

4. Open http://localhost:3000 in your browser to see your app in action. That’s it! 🎉

Node and Bun setup

If you’re in a rush, already have Node.js installed, and want to quickly set up Bun:

npm install -g bun

For a more robust setup, the recommendation in PageZERO is to use the asdf runtime version manager.

After installing asdf, run the following commands to install Node.js and Bun:

asdf plugin add nodejs
asdf plugin add bun
cd <your-project-name>
asdf install

This will read the .tool-versions file from your project root and automatically install the recommended versions of Node.js and Bun.

Project structure

PageZERO follows an integrated monorepo approach. Unlike typical monorepos, package linking happens through TypeScript’s path resolver (via tsconfig.json paths) rather than workspaces. This allows for a simpler yet modular setup.

• Directoryapps

  • Directorycore/

    • …
  • Directorycontent/ (extended in paid edition)

    • …
  • Directoryauth/ (paid edition)

    • …
  • Directorypayments/ (paid edition)

    • …
  • Directorypermissions/ (paid edition)

    • …
  • Directoryuser/ (paid edition)

    • …
  • Directoryemail/ (paid edition)

    • …
• Directorypackages/

  • Directorydb/

    • …
  • Directorygenerate/

    • …
  • Directorytypes/

    • …
  • Directoryui/ (extended in paid edition)

    • …
  • Directoryconfig/ (paid edition)

    • …
  • Directorycrypto/ (paid edition)

    • …
  • Directoryui-lite/ (paid edition)

    • …
• Directorye2e/

  • …
• Directoryworkers/

  • …
• package.json

An app is a module that owns routes, DB schema or components specific to the app domain.

A package is a module that owns utilities or UI components shared across multiple apps or other packages.

Essential 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 dev:email - boots the email development server PowerUP
• 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