DOCSEARCHbyAlgolia
Submit Docs

Wasp 0.25 Documentation

website·Indexed 34 days ago

https://wasp.sh/docs

Wasp is a tool for building modern web applications. This documentation covers version 0.25, including getting started guides, project structure, data modeling with Entities, Queries, and Actions, and built-in authentication support for Email, Username & Password, and social providers such as Google, GitHub, Keycloak, Slack, Discord, and Microsoft.

Tokens
88.2K
Snippets
507
Records
606
Agent score
71%

What's inside Wasp

  1. Overview of Wasp app deployment architecture

    Wasp applications are full-stack and consist of three primary components that must be deployed: a Node.js server, a static client, and a PostgreSQL database. These can be deployed together using 'Wasp Deploy' or independently on different platforms (e.g., Netlify for the client, Fly.io for the server, and Neon for the database).

  2. Overview of the Wasp framework

    Wasp is an opinionated full-stack web application framework that manages the client (React), server (Node.js), and database (Prisma). It uses a spec-driven approach where a central configuration file (main.wasp.ts) and a compiler generate the application structure, glue code, and deployment logic. This reduces the amount of boilerplate code needed for features like authentication, type safety, and data fetching.

  3. Overview of default global middleware in Wasp

    Wasp includes a default set of Express middleware in every application. These are applied globally to all operations (queries and actions) and API routes. The default middleware includes:

    • Helmet: Sets HTTP headers for security.
    • CORS: Enables Cross-Origin Resource Sharing (required for frontend-backend communication).
    • Morgan: HTTP request logger.
    • express.json: Parses incoming JSON request bodies (required for Wasp Operations to function).
    • express.urlencoded: Parses urlencoded bodies.
    • cookieParser: Parses the Cookie header and populates req.cookies.

  4. Overview of Wasp Auth Hooks

    Auth hooks allow developers to execute custom server-side code during the authentication process. Wasp awaits these hooks if they are defined as async functions, meaning the auth process pauses until the hook completes. Most hooks ignore return values, except for onBeforeOAuthRedirect, which can modify the OAuth redirect URL. Supported hooks include:

    • onBeforeSignup: Runs before user creation.
    • onAfterSignup: Runs after user creation.
    • onAfterEmailVerified: Runs after a user verifies their email.
    • onBeforeOAuthRedirect: Runs before redirecting to an OAuth provider.
    • onBeforeLogin: Runs before user login.
    • onAfterLogin: Runs after user login.

  5. Understand the Wasp app architecture for deployment

    A Wasp application is composed of three distinct parts that communicate over HTTP, allowing them to be deployed on the same or different servers:

    1. Client App: A React-based single-page application (SPA). It is the user interface and is typically hosted on a static file server or a CDN (e.g., Cloudflare, Netlify).
    2. Server App: A Node.js backend built with Express. It handles client requests and database interactions. It includes a Dockerfile for deployment in any Docker-supported environment.
    3. Database: Wasp uses PostgreSQL for production. This can be self-hosted or managed via a cloud service.

  6. General requirements for deploying Wasp apps

    Wasp applications can be deployed to any provider or server that meets the following three requirements:

    1. Supports running a Node.js server.
    2. Can serve static files.
    3. Can run a PostgreSQL database (or connect to one).

  7. Determine which Wasp pages to optimize for SEO

    Optimization techniques should be applied selectively based on the page type:

    • Content Pages: (e.g., landing pages, about pages, pricing). These are public-facing, provide general information, and are the primary targets for SEO and GEO to attract users and AI assistants.
    • App Pages: (e.g., dashboards, profiles, settings). These contain personalized, dynamic data and should be hidden from crawlers to protect user privacy and avoid indexing non-meaningful content.

  8. Understand Wasp Data Model Operations

    In Wasp, Operations are used to interact with the data model defined by Entities. There are two primary types of operations:

    1. Queries: Used exclusively for reading data from the database.
    2. Actions: Used for modifying data, including creating new entries or updating existing ones.

  9. Wasp AI Agent Plugin features

    The Wasp plugin for coding agents provides several key capabilities:

    • Wasp Documentation: Provides LLM-friendly documentation synced with the project's Wasp version.
    • Wasp Knowledge: Imports best practices and conventions into project memory files (e.g., CLAUDE.md, AGENTS.md).
    • Feature Configuration: Simplifies adding authentication, databases, email, and styling (Tailwind, shadcn/ui).
    • Deployment Guidance: Provides instructions for deploying to Railway, Fly.io, or other cloud providers via the Wasp CLI.

  10. Implement built-in Authentication UI in Wasp

    Wasp provides pre-generated client-side UI components for common authentication flows. These components automatically adapt their displayed providers (e.g., Email, Google, GitHub) based on the configuration in the main.wasp.ts file.
    // main.wasp.ts
import { app } from "@wasp.sh/spec"

export default app({
  name: "MyApp",
  auth: {
    methods: {
      email: {},
      google: {},
      gitHub: {},
    },
  },
})

  11. Manually deploy a Wasp app to a self-hosted server

    Manual deployment provides full control over the architecture. To self-host, you need a server with a public IP address and a domain name for HTTPS support.

    Deployment Architecture

    1. Build the server and client apps from the source code.
    2. Configure server environment variables.
    3. Deploy a database (local or managed).
    4. Run the server app (with or without Docker).
    5. Serve the client app using a static file server.
    6. Configure a reverse proxy (e.g., Nginx, Caddy, Traefik) to handle domain routing and HTTPS.

    Step-by-Step Process

    1. Install Docker, Node.js, and the Wasp CLI.
    2. Clone the app's source code to the server via Git.
    3. Run wasp install to install dependencies and wasp build to build the app.
    4. Build and run the server app using the Dockerfile located in .wasp/out. Provide environment variables via a .env file or docker run flags.
    5. Start the database (e.g., via Docker on the same server or a managed service).
    6. Build the client app into static files, located in .wasp/out/web-app.
    7. Set up a reverse proxy to serve the client static files and proxy API requests to the server app.
    8. Point your domain (e.g., myapp.com for client, api.myapp.com for server) to the server's IP address.
    wasp install
wasp build

  12. Understand the Wasp project structure

    A standard Wasp project organizes user-written code and configuration files as follows:

    • main.wasp.ts: The central Wasp specification file used to generate the app's infrastructure.
    • src/: Contains all user-written source code (TypeScript, React, Node.js). Wasp does not enforce a specific directory structure for client vs. server files.
    • schema.prisma: Defines the database models using Prisma.
    • public/: Stores static assets like images and favicons.
    • package.json: Manages project dependencies.
    • vite.config.ts: Configuration for the Vite build tool.
    • AGENTS.md / CLAUDE.md: Instructions for AI coding agents.
    .
├── AGENTS.md     # Instructions for AI coding agents.
├── CLAUDE.md     # Symlink to AGENTS.md.
├── main.wasp.ts  # Your Wasp Spec goes here.
├── package.json  # Your dependencies and project info go here.
├── public        # Your static files (e.g., images, favicon) go here.
│   └── favicon.ico
├── schema.prisma # Your database models go here.
├── src           # Your source code (TS/React/Node.js) goes here.
│   ├── Main.css
│   ├── MainPage.tsx
│   ├── assets
│   │   └── wasp-logo-rounded.svg
│   └── vite-env.d.ts
├── tsconfig.json
├── tsconfig.src.json
├── tsconfig.wasp.json
└── vite.config.ts