Zap.ts ⚡️
Introduction

Architecture

Here is the complete architecture of a Zap.ts application compared to a traditional Next.js application.

Overview

Zap.ts architecture is designed to be modular, scalable, and easy to maintain. It leverages the power of TypeScript and modern web development practices to provide a robust foundation for building applications.

Since Zap.ts is built on top of Next.js, it inherits all the features and benefits of the Next.js framework while introducing its own conventions and best practices.

Below, we will compare the architecture of a Zap.ts application with that of a traditional Next.js application.

Dependency Overview

Zap.ts builds on top of Next.js, extending its classic dependencies and adding many more for enhanced features, developer experience, and scalability. Dependencies are grouped below for clarity.

Classic Dependencies

  • next: The core React framework for server-side rendering, routing, and static site generation.
  • react: The foundational library for building user interfaces.
  • react-dom: Provides DOM-specific methods for React.
  • tailwindcss: Utility-first CSS framework for rapid UI development.

Zap.ts Additional Dependencies

Classic Dev Dependencies

  • @biomejs/biome: Fast linter and formatter for TypeScript/JavaScript.
  • @tailwindcss/postcss: PostCSS plugin for Tailwind integration.
  • @types/*: TypeScript type definitions for Node, React, etc.
  • typescript: Type-safe JavaScript development.

Zap.ts Additional Dev Dependencies

  • @react-email/preview-server: Development server for previewing React Email templates.
  • create-zap-app: CLI for creating and managing Zap.ts projects.
  • cross-env: Run scripts that set and use environment variables across platforms.
  • drizzle-kit: CLI for Drizzle ORM migrations and schema generation.
  • react-scan: Library to automatically detects performance issues in your React app.
  • ultracite: AI-powered linter/formatter for collaborative coding between humans and AI.

Zap.ts also includes many dev tools and scripts for database management, email previews, code analysis, and more, making it a full-featured boilerplate for modern web apps.

Files & Folders

In the below section, we explain all files and folders present in a typical Zap.ts project structure compared to a standard Next.js project. Next to each file, you'll find a color code (green, yellow, and red) indicating its status.

  • 🟢 Added
  • 🟡 Modified
  • 🔴 Removed

Root & Public

public/🟡
Required

Removed Vercel default files and added standard files for a better SEO (Search Engine Optimization).

public/sw.js🟢
pwa

Added a service worker for PWA (Progressive Web App) support with push notification capabilities.

public/fonts/🟢
Required

Added custom fonts for the project such as Geist.

src/app/favicon.ico🟡
Required

Replaced default Next.js favicon with Zap.ts favicon.

src/app/globals.css🟡
Required

Replaced default Next.js global styles by integrating shadcn/ui styles by default and adding custom global styles.

src/app/layout.tsx🟡
Required

Replaced default Next.js layout with a custom layout in Zap.ts with shadcn/ui integration, Geist font, additional metadata for better SEO (Search Engine Optimization), custom providers injection and Vercel analytics support depending on the environment.

Metadata

src/app/apple-icon.png🟢

Added Apple Touch Icon for better SEO (Search Engine Optimization).

src/app/fonts.ts🟢
Required

Configuration file for Geist font to be used in the application.

src/app/icon.png🟢

Added standard icon for better SEO (Search Engine Optimization).

src/app/opengraph-image/route.tsx🟢

Dynamic Open Graph image generation route using OG Image to create social media preview images on the fly.

src/app/manifest.ts🟢
pwa

Configuration file for the Web App Manifest to provide metadata for the application when installed on a device or added to the home screen as a PWA (Progressive Web App).

Error Handling

src/app/global-error.tsx🟢

Global error handling component for the application with a sophisticated error messages management.

src/app/not-found.tsx🟢

Beautiful custom 404 page for handling "Not Found" errors in the application.

IDE-Specific Files

.cursor/🟢
Cursor

Contains MCP (Model Context Protocol) that allows LLMs in Cursor to get more context with external services such as Supabase, PostHog, and more.

.cursorignore🟢
Cursor

Similar to .gitignore, this file specifies which files and directories should be ignored by Cursor.

.github/copilot-instructions.md🟢
VS Code

Contains GitHub specific files such as workflows for CI/CD, instructions for Copilot.

.vscode/🟢
VS Code

Contains Visual Studio Code specific settings and configurations such as MCP (Model Context Protocol), debugging configurations, and more.

.windsurf/🟢
Windsurf

Contains Windsurf specific settings and configurations such as MCP (Model Context Protocol).

Docker Files

.dockerignore🟢

Similar to .gitignore, this file specifies which files and directories should be ignored by Docker.

Dockerfile.dev🟢

Contains the instructions for building a Docker image provisioning a PostgreSQL database along with the application.

Dockerfile.prod🟢

Contains the instructions for building a Docker image for the application following Next.js Docker best practices.

compose.yml🟢

Contains the configuration for Docker Compose to define and run multi-container Docker applications (such as Zap.ts and PostgreSQL).

Configurations

biome.json🟢
Required

Configuration file for Biome, a linter and code formatter. We're using Ultracite preset for better collaborations between AI and developers.

next.config.ts🟡
Required

Configuration file for Next.js that includes additional settings for CSP (Content Security Policy) and Permissions Policy, sets up Typed Routes by default, adds extra security headers, configures sw.js, and supports MDX along with Bundle Analyzer.

package.json🟡
Required

Configuration file for npm with additional scripts for Biome, Drizzle ORM, Next.js, React Email and more. Also includes lint-staged configuration with Ultracite preset.

tsconfig.json🟡
Required

TypeScript configuration file with paths and settings optimized for Zap.ts such as strictNullChecks.

components.json🟢
Required

Configuration file for shadcn/ui, a set of accessible and customizable React components.

drizzle.config.dev.ts🟢
Required

Configuration file for Drizzle ORM in development mode.

drizzle.config.prod.ts🟢
Required

Configuration file for Drizzle ORM in production mode.

next-sitemap.config.js🟢
Required

Configuration file for next-sitemap, a sitemap generation tool for Next.js applications.

.gitignore🟡
Required

Specifies which files and directories should be ignored by Git, modified to include additional files and directories.

Pages

src/app/(protected)/app/(sidebar)/🟢
sidebar

Added protected routes for authenticated users with a sidebar layout. This includes pages for account management, notifications, settings, and billing. Included pages are: /app, /app/account (WIP), /app/notifications (WIP), /app/settings (WIP).

src/app/(protected)/app/billing/🟢
payments

Added billing routes for user billing information and a billing success page. Included pages are: /app/billing, /app/billing/success.

src/app/(public)/(auth)/🟢
auth

Added public authentication routes for user login, registration, password recovery, and mail verification. Included pages are: /forgot-password, /login, /mail-verified, /register, and /reset-password.

src/app/(public)/(legal)/🟢
legal

Added public legal routes for cookie policy, privacy policy, and terms of service. Included pages are: /cookie-policy, /privacy-policy, and /terms-of-service.

src/app/(public)/blog/🟢
blog

Added public blog routes for displaying blog posts and a blog landing page. This includes dynamic routing for individual blog posts based on their slug. Included pages are: /blog, /blog/[slug].

src/app/(public)/page.tsx🟢
Required

Public landing page for the application.

src/app/(public)/waitlist/🟢
waitlist

Waitlist page for users to join the waitlist. Included pages are: /waitlist.

src/app/page.tsx🔴

Default Next.js homepage, replaced by a custom homepage in Zap.ts.

Routes

src/app/api/auth/[...all]/route.ts🟢
auth

Authentication API route for handling all auth-related requests with Better Auth.

src/app/rpc/[[...rest]]/route.ts🟢
api

RPC API route for handling all RPC-related requests with oRPC.

Components

src/components/ui/🟢
Required

Various UI components from shadcn/ui. Note that Ultracite ignores this directory to keep original code as is.

Hooks

src/hooks/use-mobile.ts🟢
Required

Custom hook for detecting mobile devices and handling mobile-specific logic. This is needed by shadcn/ui.

src/hooks/utils/use-body-scroll-lock.ts🟢
components

Custom hook for managing body scroll locking in modals and other components.

src/hooks/utils/use-cooldown.ts🟢
auth

Custom hook for implementing cooldowns on actions (e.g., mail ratelimits).

Libraries

src/lib/fetch.ts🟢
auth

Custom fetch wrapper for making API requests with Zod validation and error handling, it works in Edge and Node.js environments.

src/lib/plugins.ts🟢
Required

Plugin management library for handling Zap.ts plugins.

src/lib/utils.ts🟢
Required

Utility functions such as cn (class names) that is needed by shadcn/ui.

Emails

emails/🟢
mails

Contains email templates and allows for easy customization and management of email content through a mail server using React Email.

Middleware

src/middleware.ts🟢
auth blog waitlist

Custom middleware for handling requests and responses in Zap.ts. It integrates plugins in its logic to provide a seamless experience across the application.

Providers

src/providers/providers.tsx🟢
Required

Context providers for managing global state and dependencies in Zap.ts such as ThemeProvider for theming, ProgressProvider for progress bar with BProgress, NuqsAdapter to integrate nuqs to manage search params with type safety and PluginProviders to inject providers from Zap.ts plugins.

src/providers/theme.provider.tsx🟢
Required

Theme provider for managing light and dark themes in the application with next-themes.

Instrumentation

src/instrumentation.edge.ts🟢
Required

Instrumentation for the Edge runtime environment.

src/instrumentation.node.ts🟢
Required

Instrumentation for the Node.js runtime environment.

src/instrumentation.ts🟢
Required

Shared instrumentation code for both Edge and Node.js environments, following Next.js instrumentation guidelines.

Zap.ts Specific

zap.config.ts🟢
Required

Configuration files for Zap.ts.

zap.config.types.ts🟢
Required

Type definitions for Zap.ts configuration.

zap/🟢
Required

Zap.ts plugin directories such as auth, blog, and waitlist. Each plugin contains its own routes, components, hooks, and other necessary files to provide specific functionality to the application.

Last updated on

Getting Started

Learn how to set up and configure your Zap.ts project, including environment variables, quick scripts, and CLI usage.

Deployment

Learn how to deploy your Zap.ts application to various platforms including Docker and cloud providers.