Getting Started
Learn how to set up and configure your Zap.ts project, including environment variables, quick scripts, and CLI usage.
Getting Started
Demo (in 5 minutes)
Note: This will be added soon.
Project structure
Before proceeding, ensure that Zap.ts is installed by following the instructions on the installation page and make sure to read our best practices to learn more about Zap.ts' philosophy.
Since Zap.ts is simply a Next.js starter kit, you own your code; therefore can keep what you like and get rid of things you don't need. To learn more, read the architecture page.
The src/ Directory
Zap.ts follows a classic Next.js app structure with a src/ directory. Learn more about the decisions and philosophy in the best practices guide.
Folder Structure
src/: Source code for your Next.js app.app/: Application routes and pages.components/: Reusable UI components.hooks/: Custom React hooks.lib/: Utility functions and libraries.providers/: Context and theme providers.rpc/: Remote procedure call definitions.
zap/: Modular plugins for features like analytics, auth, payments, etc.zap.config.ts: Central configuration for your app (name, plugins, SEO, etc.).next.config.ts: Next.js configuration.drizzle.config.*.ts: Database configuration for Drizzle ORM..env: Environment variables for connecting to services.
Each folder and file is designed to keep your project organized, scalable, and easy to maintain. You can add, remove, or customize any part to fit your needs. For more details, see the documentation for each plugin and configuration file.
Environment variables
The .env file connects your app to services like the database or email provider. You can remove the ones you don't need.
Update it with your own settings. Below is an example.
BETTER_AUTH_SECRET=your_better_auth_secret
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=your_database_url
DATABASE_URL_DEV=postgresql://postgres:password@localhost:5432/zap_dev
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
POLAR_ACCESS_TOKEN=your_polar_access_token
POLAR_WEBHOOK_SECRET=your_polar_webhook_secret
RESEND_API_KEY=your_resend_api_keyIf you need to generate a new .env file, you can use the following command using the CLI:
zap generate envAlso, don't forget to configure your environment variables in your Zap.ts deployment environment.
The above .env file serves as an example. You should only rely on the instance of Zap.ts that was present during its initial installation.
Configure the app
Your main configuration file is zap.config.ts, located in the root of your project. This file controls the core settings for your Zap.ts app and is designed to be clear, modular, and easy to maintain.
Here’s what you can configure:
- App Information: Set your app’s name, description, base URL, and contact emails. These values are used throughout your app and for SEO/meta tags.
- Plugin Management: Enable or disable built-in plugins like auth, analytics, payments, blog, AI, and more. Each plugin can be toggled on or off to keep your app lean and focused.
- Security Settings: Define Content Security Policy (CSP) and Permissions Policy for your app. This helps you control what resources can be loaded and what browser features are allowed, improving security and privacy.
- Default Metadata: Set up SEO and Open Graph metadata, including title, description, keywords, author, publisher, and social sharing images. These settings help your app look great in search results and when shared on social media.
You can customize any of these settings to fit your needs. The config file is fully typed and documented, so you’ll get autocompletion and validation in your editor.
Each plugin also has its own configuration file (usually zap.plugin.config.ts). For details, see the Plugins Overview.
Quick scripts
Use these commands to run Zap.ts. Pick your favorite package manager:
npm run dev # Start the dev server with Turbopack
npm run build # Build your app for production
npm run start # Run the production app
npm run lint # Check your code
npm run format # Format your code
npm run db:push # Push schema changes to database (prod)
npm run dev:db:push # Push schema changes to database (dev)
npm run db:migrate # Run database migrations (prod)
npm run dev:db:migrate # Run database migrations (dev)
npm run db:generate # Generate migration files (prod)
npm run dev:db:generate # Generate migration files (dev)
npm run db:studio # Open Drizzle Studio (prod)
npm run dev:db:studio # Open Drizzle Studio (dev)
npm run db:pull # Pull schema from database (prod)
npm run dev:db:pull # Pull schema from database (dev)
npm run dev:mail # Start email development server
npm run zap # Run Zap CLI commandsyarn dev # Start the dev server with Turbopack
yarn build # Build your app for production
yarn start # Run the production app
yarn lint # Check your code with Biome
yarn format # Format your code with Biome
yarn db:push # Push schema changes to database (prod)
yarn dev:db:push # Push schema changes to database (dev)
yarn db:migrate # Run database migrations (prod)
yarn dev:db:migrate # Run database migrations (dev)
yarn db:generate # Generate migration files (prod)
yarn dev:db:generate # Generate migration files (dev)
yarn db:studio # Open Drizzle Studio (prod)
yarn dev:db:studio # Open Drizzle Studio (dev)
yarn db:pull # Pull schema from database (prod)
yarn dev:db:pull # Pull schema from database (dev)
yarn dev:mail # Start email development server
yarn zap # Run Zap CLI commandspnpm dev # Start the dev server with Turbopack
pnpm build # Build your app for production
pnpm start # Run the production app
pnpm lint # Check your code with Biome
pnpm format # Format your code with Biome
pnpm db:push # Push schema changes to database (prod)
pnpm dev:db:push # Push schema changes to database (dev)
pnpm db:migrate # Run database migrations (prod)
pnpm dev:db:migrate # Run database migrations (dev)
pnpm db:generate # Generate migration files (prod)
pnpm dev:db:generate # Generate migration files (dev)
pnpm db:studio # Open Drizzle Studio (prod)
pnpm dev:db:studio # Open Drizzle Studio (dev)
pnpm db:pull # Pull schema from database (prod)
pnpm dev:db:pull # Pull schema from database (dev)
pnpm dev:mail # Start email development server
pnpm zap # Run Zap CLI commandsbun run dev # Start the dev server with Turbopack
bun run build # Build your app for production
bun run start # Run the production app
bun run lint # Check your code with Biome
bun run format # Format your code with Biome
bun run db:push # Push schema changes to database (prod)
bun run dev:db:push # Push schema changes to database (dev)
bun run db:migrate # Run database migrations (prod)
bun run dev:db:migrate # Run database migrations (dev)
bun run db:generate # Generate migration files (prod)
bun run dev:db:generate # Generate migration files (dev)
bun run db:studio # Open Drizzle Studio (prod)
bun run dev:db:studio # Open Drizzle Studio (dev)
bun run db:pull # Pull schema from database (prod)
bun run dev:db:pull # Pull schema from database (dev)
bun run dev:mail # Start email development server
bun run zap # Run Zap CLI commandsAdditional Development Commands
For advanced development and debugging:
npm run dev:debug # Start dev server with Node.js debugger
npm run dev:scan # Start dev server with React Scan for performance
npm run dev:trace # Start dev server with Turbopack tracing
npm run build:analyze # Build with bundle analyzer
npm run postbuild # Generate sitemap after build
npm run db:check # Check schema for issues (prod)
npm run dev:db:check # Check schema for issues (dev)
npm run db:export # Export schema (prod)
npm run dev:db:export # Export schema (dev)
npm run db:up # Apply pending migrations (prod)
npm run dev:db:up # Apply pending migrations (dev)yarn dev:debug # Start dev server with Node.js debugger
yarn dev:scan # Start dev server with React Scan for performance
yarn dev:trace # Start dev server with Turbopack tracing
yarn build:analyze # Build with bundle analyzer
yarn postbuild # Generate sitemap after build
yarn db:check # Check schema for issues (prod)
yarn dev:db:check # Check schema for issues (dev)
yarn db:export # Export schema (prod)
yarn dev:db:export # Export schema (dev)
yarn db:up # Apply pending migrations (prod)
yarn dev:db:up # Apply pending migrations (dev)pnpm dev:debug # Start dev server with Node.js debugger
pnpm dev:scan # Start dev server with React Scan for performance
pnpm dev:trace # Start dev server with Turbopack tracing
pnpm build:analyze # Build with bundle analyzer
pnpm postbuild # Generate sitemap after build
pnpm db:check # Check schema for issues (prod)
pnpm dev:db:check # Check schema for issues (dev)
pnpm db:export # Export schema (prod)
pnpm dev:db:export # Export schema (dev)
pnpm db:up # Apply pending migrations (prod)
pnpm dev:db:up # Apply pending migrations (dev)bun run dev:debug # Start dev server with Node.js debugger
bun run dev:scan # Start dev server with React Scan for performance
bun run dev:trace # Start dev server with Turbopack tracing
bun run build:analyze # Build with bundle analyzer
bun run postbuild # Generate sitemap after build
bun run db:check # Check schema for issues (prod)
bun run dev:db:check # Check schema for issues (dev)
bun run db:export # Export schema (prod)
bun run dev:db:export # Export schema (dev)
bun run db:up # Apply pending migrations (prod)
bun run dev:db:up # Apply pending migrations (dev)This list of commands may not be exhaustive and can change over time as Zap.ts evolves. Always check your local package.json for the most up-to-date command list.
Community and support
Join the Zap.ts community to showcase your apps, stay updated with the latest news, get help, and discuss with other developers.
Connect with us:
- GitHub Discussions – Perfect for feature requests, questions, and community discussions.
- Discord – Real-time chat with the community.
We're excited to see what you build with Zap.ts!
Last updated on