Skip to navigation
Framework IntegrationReact/Next.js

React/Next.js Setup

This guide walks you through setting up BAML with React/Next.js, leveraging Server Actions and React Server Components for optimal performance.

Requirements: This integration requires Next.js 15 or higher.

Example Usage

BAML automatically generates a server action and React hook for your BAML functions, with built-in support for both streaming and non-streaming modes. For details on the generated hooks, see Generated Hooks.

class Story {
  title string @stream.not_null
  content string @stream.not_null
}
function WriteMeAStory(input: string) -> Story {
  client "openai/gpt-5"
  prompt #"
    Tell me a story
    {{ ctx.output_format() }}
    {{ _.role("user") }}
    Topic: {{input}}
  "#
}

Quick Start

Follow the step-by-step instructions below to set up BAML in a new or existing Next.js project.

1

Create a New Next.js Project

First, create a new Next.js project with the App Router:

npx create-next-app@latest my-baml-app

When prompted, make sure to:

  • Select Yes for “Would you like to use TypeScript?”
  • Select Yes for “Would you like to use the App Router? (recommended)”
  • Configure other options as needed for your project
2

Install Dependencies

Next, install BAML and its dependencies:

npm install @boundaryml/baml @boundaryml/baml-nextjs-plugin
3

Configure Next.js

Update your next.config.mjs:

import { withBaml } from '@boundaryml/baml-nextjs-plugin';
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
  // ... existing config
};
export default withBaml()(nextConfig);
4

Initialize BAML

Create a new BAML project in your Next.js application:

npx baml-cli init

This will create a baml_src directory with starter code.

5

Setup Environment Variables

Setup provider specific API Keys.

.env.local
OPENAI_API_KEY=sk-...

To enable observability with BAML, you’ll first need to sign up for a Boundary Studio account.

.env.local
BOUNDARY_API_KEY=your_api_key_here
OPENAI_API_KEY=sk-...
6

Setup BAML Next.js Generator

Update the baml_src/generators.baml file to use the React/Next.js generator.

baml_src/generators.baml
generator typescript {
-  output_type "typescript"
+  output_type "typescript/react"
  output_dir "../"
  version "0.76.2"
}
7

Generate BAML Client

npx baml-cli generate

If you need baml_client to be ‘ESM’ compatible, you can add the following generator configuration to your .baml file:

generator typescript {
  ...
  module_format "esm" // the default is "cjs" for CommonJS
}
8

Generated React Hooks

BAML automatically generates type-safe Next.js server actions and React hooks for your BAML functions.

class Story {
  title string @stream.not_null
  content string @stream.not_null
}
function WriteMeAStory(input: string) -> Story {
  client "openai/gpt-5"
  prompt #"
    Tell me a story
    {{ ctx.output_format() }}
    {{ _.role("user") }}
    Topic: {{input}}
  "#
}
9

Update Package Scripts

Update your package.json scripts:

{
  "scripts": {
    "prebuild": "npm run generate",
    "generate": "baml-cli generate",
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
  }
}

Reference Documentation

For complete API documentation of the React/Next.js integration, see:

Core Concepts

Hook Configuration

Next Steps