4. Create the chatbot API route  Copy Chapter
Create a new file called chat in the app/api directory. This Next.js route handler will handle the chatbot's responses.
We're going to use the streamText function from our AI package to stream the chatbot's responses to the client. We'll also use the provider function from our AI package to get the OpenAI provider, and the log function from our Observability package to log the chatbot's responses.

5. Update the app  Copy Chapter
Finally, we'll update the app/page.tsx file to be a simple entry point that renders the chatbot UI.

6. Run the app  Copy Chapter
Run the app development server and you should be able to see the chatbot UI at http://localhost:3000.

That's it! You've now created an AI chatbot using next-forge and the built-in AI package. If you have any questions, please reach out to me on Twitter or open an issue on GitHub.
---
Content/Docs/Deployment/Docker  Copy Section
---
title: Deploying with Docker
description: How to deploy next-forge with Docker for self-hosting.
type: guide
summary: How to deploy next-forge with Docker for self-hosting.
prerequisites:
  - /docs/setup/env
related:
  - /docs/deployment/vercel
  - /docs/deployment/netlify
---
Docker lets you self-host next-forge on any platform that supports containers — such as Railway, Fly.io, Coolify, DigitalOcean App Platform, or your own server.
Enable standalone output  Copy Chapter
First, you'll need to enable Next.js standalone output in your shared config. This creates a self-contained build that includes only the files needed to run your app, significantly reducing the final image size.
In packages/next-config/index.ts, add the output property:

Create a Dockerfile  Copy Chapter
Create a Dockerfile in the root of your repository. This uses a multi-stage build to keep the final image small:

<Callout type="info">
  The CMD above uses a shell-interpolated variable. If your container runtime doesn't support this, replace ${APP_NAME} with the actual app name e.g. node apps/app/server.js.
</Callout>
Create a .dockerignore  Copy Chapter
Add a .dockerignore to speed up builds and keep secrets out of the image:

Build and run  Copy Chapter
Build and run the image for a specific app by passing the APP_NAME build argument:

Repeat for web and api if you want to deploy all three.
Using Docker Compose  Copy Chapter
If you'd prefer to run all apps together, create a docker-compose.yml:

Then run everything with:

Environment variables  Copy Chapter
When deploying with Docker, pass your environment variables at runtime using --env-file or -e flags. Do not bake secrets into the image. Learn more about how environment variables work in next-forge.
If certain variables are needed at build time (e.g. DATABASE_URL for Prisma), uncomment the relevant ARG and ENV lines in the builder stage.
---
Content/Docs/Deployment/Netlify  Copy Section
---
title: Deploying to Netlify
description: How to deploy next-forge to Netlify.
type: guide
summary: How to deploy next-forge to Netlify.
prerequisites:
  - /docs/setup/env
related:
  - /docs/deployment/vercel
---
To deploy next-forge on Netlify, you need to create 3 new projects for the app, api and web apps. After selecting your repository, change the "Site to deploy" selection to the app of choice e.g. apps/app. This should automatically detect the Next.js setup and as such, the build command and output directory.
Then, add all your environment variables to the project.
Finally, just hit "Deploy" and Netlify will take care of the rest!
Environment variables  Copy Chapter
If you're deploying on Netlify, we recommend making use of the Shared Environment Variables feature. Variables used by libraries need to exist in all packages and duplicating them can be a headache. Learn more about how environment variables work in next-forge.
---
Content/Docs/Deployment/Vercel  Copy Section
---
title: Deploying to Vercel
description: How to deploy next-forge to Vercel.
type: guide
summary: How to deploy next-forge to Vercel.
prerequisites:
  - /docs/setup/env
related:
  - /docs/deployment/netlify
---
To deploy next-forge on Vercel, you need to create 3 new projects for the app, api and web apps. After selecting your repository, change the Root Directory option to the app of choice e.g. apps/app. This should automatically detect the Next.js setup and as such, the build command and output directory.
Then, add all your environment variables to the project.
Finally, just hit "Deploy" and Vercel will take care of the rest!
Want to see it in action? next-forge is featured on the Vercel Marketplace - try deploying the app:
<VercelButton />
Environment variables  Copy Chapter
If you're deploying on Vercel, we recommend making use of the Team Environment Variables feature. Variables used by libraries need to exist in all packages and duplicating them can be a headache. Learn more about how environment variables work in next-forge.
Integrations  Copy Chapter
We also recommend installing the BetterStack and Sentry integrations. This will take care of the relevant environment variables.
---
Content/Docs/Apps/Api  Copy Section
---
title: API
description: How the "API" application works in next-forge.
type: reference
product: API
summary: How the API application works in next-forge.
related:
  - /docs/packages/security/rate-limiting
  - /docs/packages/webhooks/inbound
---
<Tip>The api application runs on port 3002. We recommend deploying it to api.{yourdomain}.com.</Tip>
next-forge exports the API from the apps/api directory. It is designed to be run separately from the main app, and is used to run isolate functions that are not part of the main user-facing application e.g. webhooks, cron jobs, etc.
Overview  Copy Chapter
The API is designed to run serverless functions, and is not intended to be used as a traditional Node.js server. However, it is designed to be as flexible as possible, and you can switch to running a traditional server if you need to.
Functionally speaking, splitting the API from the main app doesn't matter if you're running these projects on Vercel. Serverless functions are all independent pieces of infrastructure and can scale independently. However, having it run independently provides a dedicated endpoint for non-web applications e.g. mobile apps, smart home devices, etc.
Features  Copy Chapter
- Cron jobs: The API is used to run cron jobs. These are defined in the apps/api/app/cron directory. Each cron job is a .ts file that exports a route handler.
- Webhooks: The API is used to run inbound webhooks. These are defined in the apps/api/app/webhooks directory. Each webhook is a .ts file that exports a route handler.
Connecting to the API  Copy Chapter
By default, the API app only handles webhooks and cron jobs. However, you can add your own endpoints for use by the app, web, or external clients like mobile apps.
When you need the API  Copy Section
In many cases, you don't need to call the API app at all. Since app and web are both Next.js applications, they can use Server Components, Server Actions, and Route Handlers to access the database and other services directly through shared packages like @repo/database.
The API app is useful when you need:
- A dedicated endpoint for non-web clients (mobile apps, IoT devices, third-party integrations)
- A public REST API for your platform
- Long-running or resource-intensive operations isolated from your user-facing apps
Adding an endpoint  Copy Section
Create a new route handler in apps/api/app. For example, to create a /users endpoint:

Calling the API from another app  Copy Section
Each app has a NEXT_PUBLIC_API_URL environment variable pre-configured in its .env.example file, pointing to http://localhost:3002 for local development. Use this variable when making requests to the API.
From a Server Component or Server Action:

Learn more supported meta tags.
Adding a page to the navigation  Copy Chapter
To add a page to the sidebar, you'll need to define it in the mint.json file in the apps/docs directory. From the previous example, here's how you can add it to the sidebar:

Advanced  Copy Chapter
You can build the docs you want with advanced features.
<Card title="Global Settings" icon="wrench" href="https://mintlify.com/docs/settings/global" horizontal>
  Customize your documentation using the mint.json file
</Card>
<Card title="Components" icon="shapes" href="https://mintlify.com/docs/content/components" horizontal>
  Explore the variety of components available
</Card>
---
Content/Docs/Apps/Email  Copy Section
---
title: Email
description: How email templates work in next-forge
type: reference
product: Email
summary: How the email preview application works.
related:
  - /docs/packages/email
---
<Tip>The email application runs on port 3003.</Tip>
next-forge comes with react.email built in, allowing you to create and send beautiful emails using React and TypeScript.
react.email has a preview server, so you can preview the emails templates in the browser.
To preview the emails templates, simply run the email app:

---
Content/Docs/Apps/Storybook  Copy Section
---
title: Storybook
description: Frontend workshop for the design system
type: reference
product: Storybook
summary: How the Storybook design system workshop works.
related:
  - /docs/packages/design-system/components
---
<Tip>The storybook application runs on port 6006.</Tip>
next-forge uses Storybook as a frontend workshop for the design system. It allows you to interact with the components in the design system, and see how they behave in different states.
Configuration  Copy Chapter
By default, Storybook is configured with every component from shadcn/ui, and allows you to interact with them. It is also configured with the relevant fonts and higher-order components to ensure a consistent experience between your application and Storybook.
Running the workshop  Copy Chapter
Storybook will start automatically when you run bun dev. You can also start it independently with bun dev --filter storybook. The preview will be available at localhost:6006.
Adding stories  Copy Chapter
You can add your own components to the workshop by adding them to the apps/storybook/stories directory. Each component should have its own .stories.tsx file.
---
Content/Docs/Apps/Studio  Copy Section
---
title: Studio
description: Visualize and edit your database in a UI.
type: reference
product: Studio
summary: How the database studio application works.
related:
  - /docs/packages/database
---
<Tip>The studio application runs on port 3005.</Tip>
next-forge includes Prisma Studio, which is a visual editor for your database. To start it, run the following command:

---
Content/Docs/Apps/Web  Copy Section
---
title: Web
description: How the website application works in next-forge.
type: reference
product: Web
summary: How the marketing website application works.
related:
  - /docs/packages/seo/metadata
  - /docs/packages/cms/overview
---
<Tip>The web application runs on port 3001. We recommend deploying it to www.{yourdomain}.com.</Tip>
next-forge comes with a default website application, which is located in the apps/web folder.
Overview  Copy Chapter
It's built on Next.js and Tailwind CSS, with some example pages scaffolded using TWBlocks. It's designed for you to customize and extend to your needs, whether that means keeping the default pages or replacing them with your own.
Features  Copy Chapter
- Design System: The app is connected to the Design System and includes a variety of components, hooks, and utilities to help you get started.
- CMS: The app is connected to the CMS package to power your type-safe blog.
- SEO: The app is connected to the SEO package which optimizes the site for search engines.
- Analytics: The app is connected to the Analytics package to track visitor behavior.
- Observability: The app is connected to the Observability package to track errors and performance.
---
Content/Docs/Addons/C15t  Copy Section
---
title: c15t
description: How to add privacy consent management to your app with c15t.
type: integration
summary: How to add consent management with c15t.
---
Overview  Copy Chapter
c15t is an open-source consent management platform that transforms privacy consent from a compliance checkbox into a fully observable system. It provides a TypeScript-first SDK with automatic jurisdiction detection, a customizable consent banner, and support for managing third-party scripts based on user consent.
Quickstart   Copy Chapter

Installation  Copy Chapter
Install the c15t Next.js package in the app(s) that need consent management:

Setup  Copy Chapter
1. Create the provider  Copy Section

<Tip>
  For local development or prototyping, you can use mode: 'offline' instead of mode: 'c15t' to store consent in cookies without a backend.
</Tip>
2. Add to your root layout  Copy Section
Wrap your app with the ConsentManager in your root layout:

3. Configure Next.js rewrites (optional)  Copy Section
To optimize c15t further you can proxy c15t API requests through your Next.js server, which improves latency and reduces risk of blocking via an ad-blocker.

Usage  Copy Section
Here is an example of how to use joyful for generating friendly words:

Benefits  Copy Section
- Easy to Use: joyful is easy to use and generates friendly words with a simple API.
- Customizable: You can customize the number of segments and the separator.
For more information and detailed documentation, visit the joyful GitHub repo.
---
Content/Docs/Addons/Metabase  Copy Section
---
title: Metabase
description: How to add business intelligence and analytics to your app with Metabase.
type: integration
summary: How to add embedded business intelligence with Metabase.
---
While next-forge doesn't include BI tooling out of the box, you can easily add business intelligence and analytics to your app with Metabase.
Try it locally or in the cloud:
<div className="block -mt-6">
  <a href="https://www.metabase.com/start/oss" className="block -mb-6">
    <img src="https://img.shields.io/badge/Self--host-Metabase-blue?logo=metabase" alt="Self-host Metabase" />
  </a>
  <a href="https://metabase.com/start" className="block -mt-6">
    <img src="https://img.shields.io/badge/Try%20Cloud-Metabase-brightgreen?logo=metabase" alt="Try Metabase Cloud" />
  </a>
</div>
Overview  Copy Chapter
Metabase is an open-source business intelligence platform. You can use Metabase to ask questions about your data, or embed Metabase in your app to let your customers explore their data on their own.
Installing Metabase  Copy Chapter
Metabase provides an official Docker image via Docker Hub that can be used for deployments on any system that is running Docker. Here's a one-liner that will start a container running Metabase:

For full installation instructions: 
- Docker Documentation
- Jar File Documentation

Database Connection  Copy Chapter
By default, next-forge uses Neon as its database provider. Metabase works seamlessly with Postgres. To connect, you'll need:
- The hostname of the server where your database lives
- The port the database server uses
- The database name
- The username you use for the database
- The password you use for the database
You can find these details in your DATABASE_URL:

Then plug your database connection credentials into Metabase:
Metabase supports over 20 databases. For other database options, see Metabase Database Documentation.
Asking Questions and Building Dashboards  Copy Chapter
Once connected, you can start asking Questions and building Dashboards.
---
Content/Docs/Addons/Motion  Copy Section
---
title: Motion
description: A library for animating React components with ease.
type: integration
summary: How to add animations with the Motion library.
---
<Tip>Motion was formerly known as Framer Motion.</Tip>
Installation  Copy Section
To install Motion, simply run the following command:

Usage  Copy Section
Here is an example of how to use Motion to animate a component:

Benefits  Copy Section
- Easy Animation: Motion makes it easy to animate components with a simple and intuitive API.
- Customization: Motion allows you to customize animations to your needs, providing a high degree of control over the animation process.
- Performance: Motion is performant and has minimal impact on your application's performance.
For more information and detailed documentation, visit the Motion website.
---
Content/Docs/Addons/Next Safe Action  Copy Section
---
title: Next Safe Action
description: A powerful library for managing and securing your Next.js Server Actions.
type: integration
summary: How to add type-safe server actions with next-safe-action.
---
Installation  Copy Chapter
To install Next Safe Action, simply run the following command:

By default, Next Safe Action uses Zod to validate inputs, but it also supports adapters for Valibot, Yup, and Typebox.
Basic Usage  Copy Chapter
Here is a basic example of how to use Next Safe Action to call your Server Actions:
Server Action  Copy Section

Client Component  Copy Section

In this example, we create an action with input validation on the server, and call it on the client to with type-safe inputs and convinient callback utilities to simplify state management and error handling.
Benefits  Copy Chapter
- Simplified State Management: Next Safe Action simplifies server action state management by providing callbacks and status utilities.
- Type-safe: By using Zod or other validation libraries, your inputs are type-safe and validated end-to-end.
- Easy Integration: Next Safe Action is extremely easy to integrate, and you can incrementally use more of its feature like optimistic updates and middlewares.
For more information and detailed documentation, visit the Next Safe Action website.
---
Content/Docs/Addons/Nuqs  Copy Section
---
title: NUQS
description: A powerful library for managing URL search parameters in your application. It provides a simple and efficient way to handle state management through URL search parameters.
type: integration
summary: How to add type-safe URL search parameter management with nuqs.
---
Installation  Copy Section
To install NUQS, simply run the following command:

Usage  Copy Section
Here is an example of how to use NUQS for URL search parameter state management:

In this example, the useQueryState hook from nuqs is used to manage a single URL search parameter with type-safe parsing. The setQuery function updates the query URL parameter whenever the input value changes.
Benefits  Copy Section
- Simplified State Management: NUQS simplifies state management by using URL search parameters, making it easy to share and persist state across different parts of your application.
- SEO-Friendly: By using URL search parameters, NUQS helps improve the SEO of your application by making the state accessible through the URL.
- Easy Integration: NUQS is easy to integrate into your existing React application, providing a seamless experience for managing URL search parameters.
For more information and detailed documentation, visit the NUQS website.
---
Content/Docs/Addons/React Wrap Balancer  Copy Section
---
title: React Wrap Balancer
description: A simple React component that makes titles more readable
type: integration
summary: How to add balanced text wrapping with React Wrap Balancer.
---
Installation  Copy Section
To install react-wrap-balancer, simply run the following command:

Usage  Copy Section
Here is an example of how to use react-wrap-balancer to make titles more readable:

Benefits  Copy Section
- Improved Readability: react-wrap-balancer makes titles more readable by automatically wrapping them at the appropriate breakpoints.
- Easy Integration: react-wrap-balancer is easy to integrate into your existing React application, providing a seamless installation experience.
For more information and detailed documentation, visit the react-wrap-balancer website.
---
Content/Docs/Addons/Trunk  Copy Section
---
title: Trunk
description: How to add Trunk's merge queue and flaky test detection to your next-forge project.
type: integration
summary: How to add a merge queue and flaky test detection with Trunk.
---
Trunk provides a merge queue and flaky test detection for GitHub repositories. This guide covers setting up both features with your next-forge project.
Setup  Copy Chapter
Create a Trunk account at app.trunk.io and connect your GitHub repository.
Merge Queue  Copy Chapter
Trunk Merge Queue tests PRs against the predicted state of the target branch before merging, including PRs ahead of yours in the queue.
Update CI workflow triggers  Copy Section
The merge queue creates trunk-merge/ branches to test PR combinations. Your CI workflows need to run on these branches:

Apply the same change to any other workflows that must pass before merging.
Configure branch protection  Copy Section
In your GitHub repository settings under Branches > Branch protection rules for main:
- Allow the trunk-io bot to push to your protected branch
- Disable "Require branches to be up to date before merging"
- Ensure trunk-temp/ and trunk-merge/ branches are not blocked by wildcard protection rules
Guard main-only steps  Copy Section
Steps that should only run on actual merges to main (not queue test branches) need a condition:

Usage  Copy Section
Submit PRs to the queue by either:
- Checking the box in the Trunk bot's PR comment
- Commenting /trunk merge on the PR
For more information, visit the Trunk Merge Queue documentation.
Flaky Tests  Copy Chapter
Trunk Flaky Tests tracks your test results over time and identifies tests with inconsistent pass/fail behavior. It ingests JUnit XML reports uploaded from CI.
Adding JUnit reporters  Copy Section
Add the JUnit reporter to each Vitest config. In apps/app/vitest.config.mts and apps/api/vitest.config.mts:

<Tip>
  Disable automatic test retries in Vitest, as retries compromise flaky test detection accuracy.
</Tip>
Uploading results from CI  Copy Section
Add the upload step after your test command. Use if: always() so results are uploaded even when tests fail:

Required secrets  Copy Chapter
Add the following to your GitHub repository:
- TRUNK_API_TOKEN — API token from Trunk organization settings
- TRUNK_ORG_SLUG — Your Trunk organization slug (can be a repository variable)
For more information, visit the Trunk Flaky Tests documentation.
---
Content/Docs/Addons/Zustand  Copy Section
---
title: Zustand
description: A small, fast, and scalable bearbones state-management solution for React applications. It provides a simple and efficient way to manage state in your application.
type: integration
summary: How to add client-side state management with Zustand.
---
Installation  Copy Section
To install Zustand, run the following command:

Usage  Copy Section
Here is an example of how to use Zustand for state management:

In this example, the create function from Zustand is used to create a store with a count state and increment and decrement actions. The useStore hook is then used in the Counter component to access the state and actions.
Benefits  Copy Section
- Simple API: Zustand provides a simple and intuitive API for managing state in your React application.
- Performance: Zustand is optimized for performance, making it suitable for large-scale applications.
- Scalability: Zustand is scalable and can be used to manage state in applications of any size.
For more information and detailed documentation, visit the Zustand website.
---
Content/Docs/Migrations/Storage/Appwrite  Copy Section
---
title: Switch to Appwrite Storage
description: How to change the default storage provider to Appwrite Storage.
type: integration
summary: How to switch the storage provider to Appwrite Storage.
prerequisites:
  - /docs/packages/storage
related:
  - /docs/migrations/storage/upload-thing
  - /docs/migrations/authentication/appwrite
  - /docs/migrations/database/appwrite
---
Appwrite Storage is a file storage service that's part of the Appwrite platform. It provides file uploads, downloads, previews, and image transformations with built-in permission controls.
next-forge uses Vercel Blob as the default storage provider. This guide will help you switch from Vercel Blob to Appwrite Storage.
1. Replace the storage package dependencies  package dependencies')" title="Copy chapter prompt for LLMs"> Copy Chapter
Uninstall the existing Vercel Blob dependency from the storage package...

...and install the Appwrite dependencies:

2. Update environment variables  Copy Chapter
Add the following environment variables to your .env.local file:

<Note>
You'll need to create a storage bucket in the Appwrite Console first. Navigate to Storage → Create Bucket and note the bucket ID.
</Note>
3. Update the environment keys  Copy Chapter
Update the keys.ts file to validate the new environment variables:

4. Update the server storage file  Copy Chapter
Replace the contents of index.ts with a configured Appwrite Storage client:

5. Update the client storage file  Copy Chapter
Update client.ts with client-side Appwrite Storage helpers:

6. Create a storage bucket  Copy Chapter
Create a storage bucket in the Appwrite Console:
1. Go to your Appwrite project → Storage
2. Click Create Bucket
3. Give it a name (e.g., uploads)
4. Configure allowed file extensions and maximum file size
5. Set the bucket permissions (e.g., allow authenticated users to create files)
6. Copy the bucket ID and set it as APPWRITE_BUCKET_ID
You can also create a bucket programmatically:

7. File operations  Copy Chapter
Upload a file (server-side)  Copy Section

Upload a file (client-side)  Copy Section

Download a file  Copy Section

Delete a file  Copy Section

Get a file preview URL  Copy Section
Appwrite provides built-in image transformations through the preview endpoint:

Get file metadata  Copy Section

8. Update your apps  Copy Chapter
Replace Vercel Blob usage throughout your application:

9. File permissions  Copy Chapter
Appwrite supports fine-grained file-level permissions. You can set permissions when creating files:

Additional features  Copy Chapter
Image transformations  Copy Section
Appwrite Storage provides built-in image transformations without needing a separate image CDN:
- Resize (width, height)
- Crop with gravity (center, top-left, etc.)
- Quality adjustment
- Format conversion
- Border radius and background color
- Rotation and opacity
Bucket configuration  Copy Section
Each bucket can be configured with:
- Allowed file extensions — Restrict which file types can be uploaded
- Maximum file size — Set upload size limits
- Encryption — Enable at-rest encryption
- Antivirus — Scan uploaded files for malware
- Compression — Automatic file compression (gzip, zstd)
For more information, see the Appwrite Storage documentation.
---
Content/Docs/Migrations/Storage/Upload Thing  Copy Section
---
title: Switch to uploadthing
description: How to change the default storage provider to uploadthing.
type: integration
summary: How to switch the storage provider to uploadthing.
prerequisites:
  - /docs/packages/storage
---
uploadthing is a platform for storing files in the cloud. It's a great alternative to AWS S3 and it's free for small projects. Here's how to switch the default storage provider to uploadthing.
1. Swap out the required dependencies  Copy Chapter
First, uninstall the existing dependencies from the Storage package...

... and install the new dependencies...

2. Update the environment variables  Copy Chapter
Next, update the environment variables across the project, for example:

Additionally, replace all instances of BLOB_READ_WRITE_TOKEN with UPLOADTHING_TOKEN in the packages/env/index.ts file.
3. Update the existing storage files  Copy Chapter
Update the index.ts and client.ts to use the new uploadthing packages:
Storage  Copy Section

Client  Copy Section

4. Create new SSR file  Copy Chapter
We'll also need to create a new file for the storage package to handle the Tailwind CSS classes and SSR.

5. Create a file router in your app  Copy Chapter
Create a new file in your app's lib directory to define the file router. This file will be used to define the file routes for your app, using your Auth package to get the current user.

6. Create a route handler  Copy Chapter
Create a new route handler in your app's api directory to handle the file routes.

7. Update your root layout  Copy Chapter
Update your root layout to include the StorageSSRPlugin. This will add SSR hydration and avoid a loading state on your upload button.

8. Update your Tailwind CSS  Copy Chapter
Update your design system's globals.css file to include the following:

9. Create your upload button  Copy Chapter
Create a new component for your upload button. This will use the generateUploadButton function to create a button that will upload files to the imageUploader endpoint.

... and install the new dependencies...

2. Update the environment variables  Copy Chapter
Next, update the environment variables across the project, for example:

Additionally, replace all instances of STRIPE_SECRET_KEY with LEMON_SQUEEZY_API_KEY in the packages/env/index.ts file.
<Note>
The API key should be a server-side environment variable (without the NEXT_PUBLIC_ prefix), as it should not be exposed to the client.
</Note>
3. Update the payments client  Copy Chapter
Initialize the payments client in the packages/payments/index.ts file with the new API key. Then, export the lemonSqueezySetup function from the file.

4. Update the payments webhook handler  Copy Chapter
Update the webhook handler for Lemon Squeezy:

There's quite a lot you can do with Lemon Squeezy, so check out the following resources for more information:
- Webhooks Overview
- Signing Requests
5. Use Lemon Squeezy in your app  Copy Chapter
Finally, use the new payments client in your app.

---
Content/Docs/Migrations/Payments/Paddle  Copy Section
---
title: Switch to Paddle Billing
description: How to change the default payment processor to Paddle Billing.
type: integration
summary: How to switch the payment processor to Paddle Billing.
prerequisites:
  - /docs/packages/payments
related:
  - /docs/migrations/payments/lemon-squeezy
---
Paddle Billing is a merchant of record for selling digital products and subscriptions. It takes care of payments, global tax compliance, fraud prevention, localization, and subscriptions. Here's how to switch the default payment processor from Stripe to Paddle Billing.
<Note>
  This guide is for Paddle Billing, which is the latest version of Paddle. It doesn't include Paddle Classic.
</Note>

1. Swap out the required dependencies  Copy Chapter
First, uninstall the existing dependencies from the Payments package...

... and install the new dependencies...

2. Update the Payment keys  Copy Chapter
Update the required Payment keys in the packages/payments/keys.ts file:

3. Update the environment variables  Copy Chapter
Next, update the environment variables across the project, replacing the existing Stripe keys with the new Paddle keys:

4. Update the payments client  Copy Chapter
Initialize the payments client in the packages/payments/index.ts file with the new API key.

5. Update the payments webhook handler  Copy Chapter
Update the webhook handler for Paddle:

There's quite a lot you can do with Paddle, so check out the following resources for more information:
- Webhooks Overview
- Signature Verification
- Simulate Webhooks
6. Create a Checkout hook  Copy Chapter
Create a new file for checkout and install paddle-js:

Then, create a new hook to initialize Paddle in the packages/payments/checkout.tsx file:

7. Use the Checkout hook  Copy Chapter
Finally, open a checkout on your pricing page:

---
Content/Docs/Migrations/Notifications/Novu  Copy Section
---
title: Switch to Novu
description: How to change the notifications provider to Novu.
type: integration
summary: How to switch the notifications provider to Novu.
prerequisites:
  - /docs/packages/notifications
---
Novu is an open-source notification infrastructure platform that supports in-app, email, SMS, push, and chat channels. It's self-hostable and provides a unified API for managing notifications across multiple channels. Here's how to switch the default notifications provider from Knock to Novu.
1. Swap out the required dependencies  Copy Chapter
First, uninstall the existing dependencies from the Notifications package...

... and install the new dependencies...

2. Update the Notification keys  Copy Chapter
Update the required Notification keys in the packages/notifications/keys.ts file:

3. Update the environment variables  Copy Chapter
Next, update the environment variables across the project, replacing the existing Knock keys with the new Novu keys:

4. Update the notifications client  Copy Chapter
Initialize the notifications client in the packages/notifications/index.ts file with the new API key:

5. Update the notifications provider  Copy Chapter
Replace the Knock provider with Novu's NovuProvider in packages/notifications/components/provider.tsx:

6. Update the notifications trigger  Copy Chapter
Replace the Knock notification components with Novu's Inbox in packages/notifications/components/trigger.tsx:

You can also remove the packages/notifications/styles.css file, as Novu's Inbox component handles its own styling.
7. Update the app-level notifications provider  Copy Chapter
Update the wrapper in apps/app/app/(authenticated)/components/notifications-provider.tsx. The existing wrapper should work as-is since the NotificationsProvider already accepts a theme prop. If the types differ, update accordingly:

8. Triggering notifications  Copy Chapter
To trigger a notification from the server, use the Novu API:

There's quite a lot you can do with Novu, so check out the following resources for more information:
- Novu Documentation
- Workflows
- Inbox Component
- Self-hosting
---
Content/Docs/Migrations/Formatting/Eslint  Copy Section
---
title: Switch to ESLint
description: How to change the default linter to ESLint.
type: integration
summary: How to switch the linter to ESLint.
prerequisites:
  - /docs/packages/formatting
---
Here's how to switch from Biome to ESLint. In this example, we'll also add the Next.js and React plugins, as well as the new ESLint Flat Config.
1. Swap out the required dependencies  Copy Chapter
First, uninstall the existing dependencies from the root package.json file...

...and install the new ones:

2. Configure ESLint  Copy Chapter
Delete the existing biome.json file in the root of the project, and create a new eslint.config.mjs file:

3. Install the ESLint VSCode extension  Copy Chapter
<Tip>
This is generally installed if you selected "JavaScript" as a language to support when you first set up Visual Studio Code.
</Tip>
Install the ESLint VSCode extension to get linting and formatting support in your editor.
4. Update your .vscode/settings.json file  file')" title="Copy chapter prompt for LLMs"> Copy Chapter
Add the following to your .vscode/settings.json file to match the following:

5. Re-enable the lint script  script')" title="Copy chapter prompt for LLMs"> Copy Chapter
As Next.js uses ESLint for linting, we can re-enable the lint script in the root package.json files. In each of the Next.js apps, update the package.json file to include the following:

---
Content/Docs/Migrations/Flags/Hypertune  Copy Section
---
title: Switch to Hypertune
description: How to change the feature flag provider to Hypertune.
type: integration
summary: How to switch the feature flag provider to Hypertune.
prerequisites:
  - /docs/packages/flags
---
Hypertune is the most flexible platform for feature flags, A/B testing, analytics and app configuration. Built with full end-to-end type-safety, Git version control and local, synchronous, in-memory flag evaluation. Optimized for TypeScript, React and Next.js.
Here's how to switch your next-forge project to use Hypertune for feature flags!
1. Create a new Hypertune project  Copy Chapter
Go to Hypertune and create a new project using the next-forge template. Then go to the Settings page of your project and copy the main token.
2. Update the environment variables  Copy Chapter
Update the environment variables across the project. For example:

Add a .env file to the feature-flags package with the following contents:

3. Update the keys.ts file in the feature-flags package  file in the feature-flags package')" title="Copy chapter prompt for LLMs"> Copy Chapter
Use the NEXT_PUBLIC_HYPERTUNE_TOKEN environment variable in the call to createEnv:

4. Swap out the required dependencies  Copy Chapter
First, delete the create-flag.ts file.
Then, uninstall the existing dependencies from the feature-flags package:

Then, install the new dependencies:

5. Set up Hypertune code generation  Copy Chapter
Add analyze and build scripts to the package.json file for the feature-flags package, which both execute the hypertune command:

Then run code generation with the following command:

This will generate the following files:

6. Set up Hypertune client instance  Copy Chapter
Add a getHypertune.ts file in the feature-flags package which defines a getHypertune function that returns an initialized instance of the Hypertune SDK on the server:

7. Update index.ts ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Hypertune automatically generates feature flag functions that use the flags package. To export them the same way as before, update the index.ts file to export everything from the generated/hypertune.vercel.ts file:

Hypertune adds a Flag suffix to all these generated feature flag functions, so you will need to update flag usages with this, e.g. showBetaFeature => showBetaFeatureFlag.
8. Add more feature flags  Copy Chapter
To add more feature flags, create them in the Hypertune UI and then re-run code generation. They will be automatically added to your generated files.
---
Content/Docs/Migrations/Documentation/Fumadocs  Copy Section
---
title: Switch to Fumadocs
description: How to change the documentation provider to Fumadocs.
type: integration
summary: How to switch the documentation provider to Fumadocs.
prerequisites:
  - /docs/apps/docs
---
Fumadocs is a beautiful & powerful docs framework powered by Next.js, allowing advanced customisations.
1. Create a Fumadocs App  Copy Chapter
Fumadocs is similar to a set of libraries built on Next.js App Router, which works very differently from a hosted solution like Mintlify, or other frameworks/static site generator that takes complete control over your app.
To begin, you can use a command to initialize a Fumadocs app quicky:

Here we assume you have enabled Fumadocs MDX, Tailwind CSS, and without a default ESLint config.
What is a Content Source?  Copy Section
The input/source of your content, it can be a CMS, or local data layers like Content Collections and Fumadocs MDX (the official content source).
Fumadocs is designed carefully to allow a custom content source, there's also examples for Sanity if you are interested.
<Note>lib/source.ts is where you organize code for content sources.</Note>
Update your Tailwind CSS  Copy Section
Start the app with bun dev.
If some styles are missing, it could be due to your monorepo setup, you can change the content property in your Tailwind CSS config (tailwind.config.mjs) to ensure it works:

You can either keep the Tailwind config file isolated to the docs, or merge it with your existing config from the tailwind-config package.
2. Migrate MDX Files  Copy Chapter
Fumadocs, same as Mintlify, utilize MDX for content files. You can move the .mdx files from your Mintlify app to content/docs directory.
<Note>Fumadocs requires a title frontmatter property.</Note>
The MDX syntax of Fumadocs is almost identical to Mintlify, despite from having different components and usage for code blocks. Visit Markdown for supported Markdown syntax.
Code Block  Copy Section
Code block titles are formatted with title="Title".
#### Before

</CodeGroup>

</Tabs>

Adding Components  Copy Section
To use components without import, add them to your MDX component.

3. Migrate mint.json File  File')" title="Copy chapter prompt for LLMs"> Copy Chapter
Instead of a single file, you can configure Fumadocs using code.
Sidebar Items  Copy Section
The sidebar items are generated from your file system, Fumadocs takes meta.json as the configurations of a folder.
You don't need to hardcode the sidebar config manually.
For example, to customise the order of pages in content/docs/components folder, you can create a meta.json folder in the directory:

Fumadocs also support the rest operator (...) if you want to include the other pages.

Visit the Pages Organization Guide for an overview of supported syntaxs.
Appearance  Copy Section
The overall theme can be customised using CSS variables and/or presets.
#### CSS variables
In your global CSS file:

See all available presets.
Layout Styles  Copy Section
You can open app/layout.config.tsx, it contains the shared options for layouts.
Fumadocs offer a default Docs Layout for documentation pages, and Home Layout for other pages.
You can customise the layouts in layout.tsx.
Search  Copy Section
app/api/search/route.ts contains the Route Handler for search, it is powered by Orama by default.
Navigation Links  Copy Section
Navigation links are passed to layouts, you can also customise them in your Layout config.

See all supported items.
Done  Copy Chapter
Now, you should be able to build and preview the docs.
Visit Fumadocs for details and additional features.
---
Content/Docs/Migrations/Database/Appwrite  Copy Section
---
title: Switch to Appwrite Databases
description: How to change the database provider to Appwrite Databases.
type: integration
summary: How to switch the database provider to Appwrite Databases.
prerequisites:
  - /docs/packages/database
related:
  - /docs/migrations/database/supabase
  - /docs/migrations/authentication/appwrite
  - /docs/migrations/storage/appwrite
---
Appwrite Databases is a document database service that's part of the Appwrite platform. It provides a flexible schema system with collections, documents, and built-in permissions.
next-forge uses Neon as the database provider with Prisma as the ORM. This guide will help you switch from Neon and Prisma to Appwrite Databases.
<Warning>
Appwrite uses a document database model, not SQL. There is no Prisma ORM equivalent — you'll use Appwrite's SDK and Query builder instead. Your data model will need to be restructured around collections and documents rather than relational tables.
</Warning>
1. Replace the database package dependencies  package dependencies')" title="Copy chapter prompt for LLMs"> Copy Chapter
Uninstall the existing Neon and Prisma dependencies from the database package...

...and install the Appwrite dependency:

2. Update environment variables  Copy Chapter
Add the following environment variables to your .env.local file. You can find these values in your Appwrite project's Settings page:

<Note>
You'll need to create a database in the Appwrite Console first. The APPWRITE_DATABASE_ID is the ID of the database you create.
</Note>
3. Update the environment keys  Copy Chapter
Update the keys.ts file to validate the new environment variables:

4. Update the database package  Copy Chapter
Replace the contents of index.ts with a configured Appwrite Databases client:

5. Remove Prisma files  Copy Chapter
Delete the Prisma-specific files that are no longer needed:

Also remove any Prisma-related scripts from your package.json files (e.g., migrate, generate, studio).
6. Understanding Appwrite's data model  Copy Chapter
Appwrite organizes data differently from SQL databases:
| SQL (Prisma) | Appwrite |
| --- | --- |
| Database | Database |
| Table | Collection |
| Row | Document |
| Column | Attribute |
| Migration | Console / SDK |
Collections are defined with typed attributes (string, integer, boolean, float, email, enum, URL, IP, datetime, relationship) and can be created via the Appwrite Console or programmatically with the SDK.
7. Create collections  Copy Chapter
You can create collections through the Appwrite Console, or programmatically using the server SDK. Here's an example of creating a posts collection:

Then define its attributes:

<Note>
For most projects, it's easier to create collections and attributes through the Appwrite Console UI rather than programmatically.
</Note>
8. Perform CRUD operations  Copy Chapter
Here's how to perform basic CRUD operations with the Appwrite SDK:
Create a document  Copy Section

Read documents  Copy Section

Update a document  Copy Section

Delete a document  Copy Section

9. Permissions  Copy Chapter
Appwrite uses a document-level permissions system instead of SQL's Row Level Security. You can set permissions when creating or updating documents:

Common permission patterns:
- Role.any() — Anyone (including guests)
- Role.users() — Any authenticated user
- Role.user('userId') — A specific user
- Role.team('teamId') — Members of a specific team
- Role.team('teamId', 'admin') — Team members with a specific role
10. Update your apps  Copy Chapter
Replace Prisma queries throughout your application with Appwrite SDK calls:

Additional features  Copy Chapter
Realtime subscriptions  Copy Section
Appwrite supports realtime subscriptions on the client side. You can listen for changes to documents:

Indexes  Copy Section
For better query performance, create indexes on frequently queried attributes:

For more information, see the Appwrite Databases documentation.
---
Content/Docs/Migrations/Database/Convex  Copy Section
---
title: Switch to Convex
description: How to change the database provider to Convex.
type: integration
summary: How to switch the database provider to Convex.
prerequisites:
  - /docs/packages/database
---
Convex is a reactive database platform with real-time sync, TypeScript-first backend functions, and fully managed infrastructure. Unlike traditional databases, Convex combines the database, server functions, and real-time subscriptions into a single platform.
next-forge uses Neon as the database provider with Prisma as the ORM. This guide will provide the steps you need to switch the database provider from Neon to Convex. Since Convex replaces both the database and ORM layers, this is a more significant change than switching between SQL databases.
Here's how to switch from Neon to Convex for your next-forge project.
1. Sign up to Convex  Copy Chapter
Create a free account at convex.dev. You can manage your projects through the Convex Dashboard.
2. Replace the dependencies  Copy Chapter
Uninstall the existing dependencies...

... and install Convex:

3. Initialize Convex  Copy Chapter
From the root of your project, run:

This will prompt you to log in, create a new project, and generate a convex/ directory in your project root with the configuration files. It will also create a .env.local file with your CONVEX_DEPLOYMENT and NEXT_PUBLIC_CONVEX_URL variables.
4. Set up the Convex client provider  Copy Chapter
Create a client component to wrap your app with the Convex provider. Add this to your app:

Then wrap your app layout with the provider:

5. Update the database package  Copy Chapter
Replace the contents of the database package's main export. Since Convex uses its own function system instead of a traditional client, the export changes significantly:

Delete the prisma/ directory from @repo/database:

Update keys.ts to use the Convex environment variable:

6. Define your schema  Copy Chapter
Create a schema file in the convex/ directory. Here's an example equivalent to the default Prisma Page model:

Run npx convex dev to push your schema to Convex and generate types.
7. Write queries and mutations  Copy Chapter
Create server functions for your data access. Convex uses its own function system instead of raw SQL or an ORM:

8. Update your app code  Copy Chapter
Convex uses React hooks for data fetching with automatic real-time updates. Update your components to use useQuery and useMutation:

<Note>
Convex queries are reactive by default — your UI will automatically update when the underlying data changes, without any additional configuration.
</Note>
For server-side data fetching (e.g. in Server Components), use the Convex HTTP client:

9. Replace Prisma Studio  Copy Chapter
Delete the now unused Prisma Studio app:

To manage your data, use the Convex Dashboard which provides a data browser, function logs, and deployment management.
10. Deploy  Copy Chapter
When deploying your app, set the NEXT_PUBLIC_CONVEX_URL environment variable in your hosting provider (e.g. Vercel). You can find this URL in your Convex Dashboard under your project's settings.
To deploy your Convex functions to production, run:

This deploys your schema and server functions to your production Convex instance.
---
Content/Docs/Migrations/Database/Drizzle  Copy Section
---
title: Switch to Drizzle
description: How to change the ORM to Drizzle.
type: integration
summary: How to switch the ORM to Drizzle.
prerequisites:
  - /docs/packages/database
related:
  - /docs/migrations/database/prisma-postgres
---
Drizzle is a brilliant, type-safe ORM growing quickly in popularity. If you want to switch to Drizzle, you have two options:
1. Keep Prisma and add the Drizzle API to the Prisma client. Drizzle have a great guide on how to do this.
2. Go all-in and switch to Drizzle.
Here, we'll assume you have a working Neon database and cover the second option.
<Callout type="warn">
Before starting, make sure your Prisma schema has been pushed to your database (e.g. by running npx prisma db push in packages/database). The drizzle-kit pull command in Step 4 introspects the live database — if no tables exist yet, it will generate an empty schema file.
</Callout>
1. Swap out the required dependencies in @repo/database ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Uninstall the existing dependencies...

...and install the new ones:

2. Update the database connection code  Copy Chapter
Delete everything in @repo/database/index.ts and replace it with the following:

3. Create a drizzle.config.ts file  file')" title="Copy chapter prompt for LLMs"> Copy Chapter
Next we'll create a Drizzle configuration file, used by Drizzle Kit and contains all the information about your database connection, migration folder and schema files. Create a drizzle.config.ts file in the packages/database directory with the following contents:

4. Generate the schema file  Copy Chapter
Drizzle uses a schema file to define your database tables. Rather than create one from scratch, you can generate it from the existing database. In the packages/database folder, run the following command to generate the schema file:

This should pull the schema from the database, creating a schema.ts file containing the table definitions and some other files.
If the generated schema.ts is empty, your database likely has no tables yet. You can either push your Prisma schema first (npx prisma db push) and re-run the pull, or create the schema manually. For example, the default next-forge Page model translates to:

5. Update your queries  Copy Chapter
Now you can update your queries to use the Drizzle ORM.
For example, here's how we can update the page query in app/(authenticated)/page.tsx:

6. Remove Prisma Studio  Copy Chapter
You can also delete the now unused Prisma Studio app located at apps/studio:

7. Update the migration script in the root package.json ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Change the migration script in the root package.json from Prisma to Drizzle. Update the migrate script to use Drizzle commands:

---
Content/Docs/Migrations/Database/Edgedb  Copy Section
---
title: Switch to EdgeDB
description: How to change the database provider to EdgeDB.
type: integration
summary: How to switch the database provider to EdgeDB.
prerequisites:
  - /docs/packages/database
---
EdgeDB is an open-source Postgres data layer designed to address major ergonomic SQL and relational schema modeling limitations while improving type safety and performance.
<Note>
EdgeDB rebranded to "Gel" in February 2025. The edgedb npm packages and CLI commands still work via compatibility shims. See the Gel announcement for details.
</Note>
next-forge uses Neon as the database provider with Prisma as the ORM as well as Clerk for authentication. This guide will provide the steps you need to switch the database provider from Neon to EdgeDB.
<Note>
 For authentication, another guide will be provided to switch to EdgeDB Auth with access policies, social 
 auth providers, and more.
</Note>
Here's how to switch from Neon to EdgeDB for your next-forge project.
1. Create a new EdgeDB database   Copy Chapter
Create an account at EdgeDB Cloud. Once done, create a new instance (you can use EdgeDB's free tier). We'll later connect to it through the EdgeDB CLI.
2. Swap out the required dependencies in @repo/database ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Uninstall the existing dependencies...

... and install the new dependencies:

3. Setup EdgeDB in @repo/database package  package')" title="Copy chapter prompt for LLMs"> Copy Chapter
In the @repo/database directory, run:

<Note>
Replace <org_name> and <instance_name> with the EdgeDB's organization and instance you've previously created in the EdgeDB Cloud.
</Note>
The init command creates a new subdirectory called dbschema, which contains everything related to EdgeDB:

This command also links your environment to the EdgeDB Cloud instance, allowing the EdgeDB client libraries to automatically connect to it without any additional configuration.
You can also delete prisma/ directory from the @repo/database:

4. Update the database connection code  Copy Chapter
Update the database connection code to use an EdgeDB client:

5. Update the schema file and generate types  Copy Chapter
Now, you can modify the database schema:

And apply your changes by running:

Once complete, you can also generate a TypeScript query builder and types from your database schema:

These commands introspect the schema of your database and generate code in the dbschema directory.
6. Update your queries  Copy Chapter
Now you can update your queries to use the EdgeDB client.
For example, here’s how we can update the page query in app/(authenticated)/page.tsx:

7. Replace Prisma Studio with EdgeDB UI  Copy Chapter
You can also delete the now unused Prisma Studio app located at apps/studio:

To manage your database and browse your data, you can run:

8. Extract EdgeDB environment variables for deployment  Copy Chapter
When deploying your app, you need to provide the EDGEDB_SECRET_KEY and EDGEDB_INSTANCE environment variables in your app's cloud provider to connect to your EdgeDB Cloud instance.
You can generate a dedicated secret key for your instance with npx edgedb cloud secretkey create or via the web UI's "Secret Keys" pane in your instance dashboard.
---
Content/Docs/Migrations/Database/Planetscale  Copy Section
---
title: Switch to PlanetScale
description: How to change the database provider to PlanetScale.
type: integration
summary: How to switch the database provider to PlanetScale.
prerequisites:
  - /docs/packages/database
---
Here's how to switch from Neon to PlanetScale.
<Warning>
PlanetScale removed their free/Hobby tier in March 2024. The minimum plan now starts at $39/month. Keep this in mind when evaluating PlanetScale for your project.
</Warning>
1. Create a new database on PlanetScale  Copy Chapter
Once you create a database on PlanetScale, you will get a connection string. It will look something like this:

Keep this connection string handy, you will need it in the next step.
2. Update your environment variables  Copy Chapter
Update your environment variables to use the new PlanetScale connection string:

Etcetera.
3. Swap out the required dependencies in @repo/database ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Uninstall the existing dependencies...

...and install the new ones:

4. Update the database connection code  Copy Chapter
Update the database connection code to use the new PlanetScale adapter:

5. Update your Prisma schema  Copy Chapter
Update your Prisma schema to use the new database provider:

6. Add a dev script  script')" title="Copy chapter prompt for LLMs"> Copy Chapter
Add a dev script to your package.json:

---
Content/Docs/Migrations/Database/Prisma Postgres  Copy Section
---
title: Switch to Prisma Postgres
description: How to change the database provider to Prisma Postgres.
type: integration
summary: How to switch the database provider to Prisma Postgres.
prerequisites:
  - /docs/packages/database
related:
  - /docs/migrations/database/drizzle
---
Here's how to switch from Neon to Prisma Postgres — a serverless database with zero cold starts and a generous free tier. You can learn more about its architecture that enables this here.
1. Create a new Prisma Postgres instance  Copy Chapter
Start by creating a new Prisma Postgres instance via the Prisma Data Platform and get your connection string. It will look something like this:

2. Update your environment variables  Copy Chapter
Update your environment variables to use the new Prisma Postgres connection string:

3. Swap out the required dependencies in @repo/database ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Uninstall the existing dependencies...

... and install the new dependencies:

4. Update the database connection code  Copy Chapter
Update the database connection code to use the new Prisma Postgres adapter:

Your project is now configured to use your Prisma Postgres instance for migrations and queries.
5. Explore caching and real-time database events  Copy Chapter
Note that thanks to the first-class integration of other Prisma products, Prisma Postgres comes with additional features out-of-the-box that you may find useful:
- Prisma Accelerate: Enables connection pooling and global caching
- Prisma Pulse: Enables real-time streaming of database events
Caching  Copy Section
To cache a query with Prisma Client, you can add the swr and ttl options to any given query, for example:

Learn more in the Accelerate documentation.
Real-time database events  Copy Section
<Warning>
Prisma Pulse (@prisma/extension-pulse) has been paused and may be deprecated. Check the Prisma Pulse documentation for the latest status before proceeding.
</Warning>
To stream database change events from your database, you first need to install the Pulse extension:

Next, you need to add your Pulse API key as an environment variable:

<Info>
  You can find your Pulse API key in your Prisma Postgres connection string, it's the value of the api_key argument and starts with ey.... Alternatively, you can find the API key in your Prisma Postgres Dashboard.
</Info>
Then, update the env package to include the new PULSE_API_KEY environment variable:

Finally, update the database connection code to include the Pulse extension:

You can now stream any change events from your database using the following code:

<Note>
pgbouncer=true disables Prisma from generating prepared statements. This is required since our connection pooler does not support prepared statements in transaction mode yet. The connection_limit=1 parameter is only required if you are using Prisma from a serverless environment.
</Note>
4. Replace the dependencies  Copy Chapter
Prisma doesn't have a Supabase adapter yet, so we just need to remove the Neon adapter and connect to Supabase directly.
First, remove the Neon dependencies from the project...

... and add the Supabase dependencies:

5. Update the database package  Copy Chapter
Update the database package. We'll remove the Neon extensions and connect to Supabase directly, which should automatically use the environment variables we set earlier.

6. Update the Prisma schema  Copy Chapter
Update the prisma/schema.prisma file so it contains the DIRECT_URL. This allows us to use the Prisma CLI to perform other actions on our database (e.g. migrations) by bypassing Supavisor.

<Note>
You don't need relationMode = "prisma" here — Supabase is PostgreSQL and supports foreign keys natively. Only add it if you specifically need Prisma to emulate relations (e.g., for compatibility with databases that don't support foreign keys).
</Note>
Now you can run the migration from the root of your next-forge project:

7. Set up Row Level Security (RLS)  Copy Chapter
Row Level Security (RLS) is a powerful PostgreSQL feature that allows you to control access to database rows based on the authenticated user. This is essential for multi-tenant applications where users should only see their own data.
<Note>
RLS policies use auth.uid() to get the authenticated user's ID from Supabase Auth. Make sure you've completed the Supabase Auth migration first.
</Note>
Enable RLS on your tables  Copy Section
First, enable RLS on the tables you want to protect. You can do this via the Supabase dashboard or by running SQL migrations:

Create RLS policies  Copy Section
Once RLS is enabled, create policies that define who can access what data:
#### Organization policies

#### Organization member policies

Testing RLS policies  Copy Section
You can test your RLS policies using the Supabase SQL Editor with the following pattern:

Common RLS patterns  Copy Section
#### User-owned data
For data that belongs directly to a user (like user profiles or settings):

#### Tenant isolation
For multi-tenant data where access is determined by an organization or tenant ID:

#### Public read, authenticated write
For data that everyone can read but only authenticated users can modify:

<Warning>
When RLS is enabled on a table, all access is denied by default. You must create policies to allow access. Make sure to test thoroughly to avoid accidentally blocking legitimate access.
</Warning>
For more information, see the Supabase Row Level Security guide.
---
Content/Docs/Migrations/Database/Turso  Copy Section
---
title: Switch to Turso
description: How to change the database provider to Turso.
type: integration
summary: How to switch the database provider to Turso.
prerequisites:
  - /docs/packages/database
---
Turso is multi-tenant database platform built for all types of apps, including AI apps with on-device RAG, local-first vector search, offline writes, and privacy-focused data access with low latency.
Here's how to switch from Neon to Turso for your next-forge project.
1. Sign up to Turso  Copy Chapter
You can use the Dashboard, or the CLI to manage your account, database, and auth tokens.
_We'll be using the CLI throughout this guide._
2. Create a Database  Copy Chapter
Create a new database and give it a name using the Turso CLI:

You can now fetch the URL to the database:

It will look something like this:

3. Create a Database Auth Token  Copy Chapter
You will need to create an auth token to connect to your Turso database:

4. Update your environment variables  Copy Chapter
Update your environment variables to use the new Turso connection string:

Etcetera.
Now inside packages/env/index.ts, add DATABASE_AUTH_TOKEN to the server and runtimeEnv objects:

5. Install @libsql/client  Copy Chapter
The @libsql/client is used to connect to the hosted Turso database.
Uninstall the existing dependencies for Neon...

... and install the new dependencies for Turso & libSQL:

6. Update the database connection code  Copy Chapter
Open packages/database/index.ts and make the following changes:

7. Apply schema changes  Copy Chapter
Now connect to the Turso database using the CLI:

And apply the schema to the database:

8. Update application code  Copy Chapter
Now wherever you would usually call Prisma, use the libsql client instead:

... and install the new dependencies...

2. Update the .gitignore file  file')" title="Copy chapter prompt for LLMs"> Copy Chapter
Add .content-collections to the root .gitignore file (in the root of your monorepo):

3. Modify the CMS package scripts  Copy Chapter
Now we need to modify the CMS package scripts to replace the basehub commands with content-collections.

<Note>
  We're using the Content Collections CLI directly to generate the collections prior to Next.js processes. The files are cached and not rebuilt in the Next.js build process. This is a workaround for this issue.
</Note>
4. Modify the relevant CMS package files  Copy Chapter
<Note>
  You may see TypeScript errors during this step. These will be resolved after you create your collections configuration and run the first build in step 6.
</Note>
Next.js Config (CMS Package)  Copy Section
Update the CMS package's Next.js config to export the Content Collections wrapper:

This replaces the previous BaseHub configuration and maintains compatibility with your existing next.config.ts in the web app.
Collections  Copy Section

Components  Copy Section

TypeScript Config  Copy Section
Update your tsconfig.json in the apps/web directory to add the path mapping:

<Note>
  Make sure to merge this with your existing compilerOptions.paths if you have any.
</Note>
Toolbar  Copy Section

Table of Contents  Copy Section

6. Create your collections  Copy Chapter
Create a new content collections configuration file in the cms package, then create a re-export file in the web app.
<Note>We're remapping the title field to _title and the _meta.path field to _slug to match the default next-forge CMS.</Note>
CMS Package  Copy Section

Web App  Copy Section
Create a configuration file in the root of your web app:

<Note>
  After creating these files, you'll need to run bun run build in the packages/cms directory to generate the types. TypeScript errors about missing content-collections module will resolve after the first build.
</Note>
7. Create your content  Copy Chapter
Create the content directories if they don't exist:
- apps/web/content/blog for blog posts
- apps/web/content/legal for legal pages
To create a new blog post, add a new MDX file to the apps/web/content/blog directory. The file name will be used as the slug for the blog post and the frontmatter will be used to generate the blog post page. For example:

The same concept applies to the legal collection, which is used to generate the legal policy pages. Also, the image field is the path relative to the app's root public directory.
8. Remove the environment variables  Copy Chapter
Finally, remove all instances of BASEHUB_TOKEN from the @repo/env package.
9. Bonus features  Copy Chapter
Fumadocs MDX Plugins  Copy Section
You can use the Fumadocs MDX plugins to enhance your MDX content.

Reading Time  Copy Section
You can calculate reading time for your collection by adding a transform function.

Low-Quality Image Placeholder (LQIP)  Copy Section
You can generate a low-quality image placeholder for your collection by adding a transform function.

...and install the Appwrite dependencies:

2. Update environment variables  Copy Chapter
Add the following environment variables to your .env.local file in each Next.js application (app, web, and api). You can find these values in your Appwrite project's Settings page:

<Note>
The endpoint and project ID are safe to use in client-side code. The API key should only be used server-side.
</Note>
3. Update the environment keys  Copy Chapter
Update the keys.ts file to validate the new Appwrite environment variables:

4. Create the server client  Copy Chapter
Create a server-side Appwrite client using node-appwrite with cookie-based session management:

5. Create the browser client  Copy Chapter
Create a client-side Appwrite client:

6. Update the middleware  Copy Chapter
Replace proxy.ts with middleware.ts to handle session validation:

<Note>
Delete the old proxy.ts file if it exists, as it was specific to Clerk's proxy functionality.
</Note>
7. Update the Provider file  Copy Chapter
Appwrite Auth doesn't require a Provider component, so replace it with a stub:

8. Update the auth components  Copy Chapter
Update both the sign-in.tsx and sign-up.tsx components to use Appwrite Auth:
Sign In  Copy Section

Sign Up  Copy Section

9. Set up auth callback route for OAuth  Copy Chapter
Create a callback route to handle OAuth redirects: