Native / platform steps: This project is designed to run with Bun as the package manager (bunfig.toml is present). Replace npm install above with bun install if using Bun. Database migrations require bunx prisma migrate deploy. No iOS/Android linking is required.

Project setup

1. Drop source: Place the source/ directory at your repo root or as a git subtree. The workspace root is . (the monorepo root).

2. Install dependencies:

   bun install
   # or: npm install (with Node >=20)
   

3. Configure environment variables: Copy and populate env files for each app:

   cp apps/builder/.env.example apps/builder/.env.local
   cp apps/viewer/.env.example apps/viewer/.env.local
   

   Minimum required vars for the builder:

   DATABASE_URL=postgresql://user:pass@localhost:5432/typebot
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=<random-secret>
   ENCRYPTION_SECRET=<32-char-secret>
   NEXT_PUBLIC_VIEWER_URL=http://localhost:3001
   

4. Wire TypeScript paths: The root tsconfig.base.json defines workspace aliases. In your consuming tsconfig.json:

   {
     "extends": "./source/tsconfig.base.json",
     "compilerOptions": {
       "baseUrl": "."
     }
   }
   

5. Run database migrations:

   cd source
   bunx prisma migrate deploy --schema packages/prisma/schema.prisma
   

6. Start the builder in development:

   cd source
   bun run dev --filter=@typebot.io/builder
   # or via docker:
   docker compose -f docker-compose.dev.yml up
   

7. Run tests:

   cd source
   bun run test
   

Public API

ImageUploadContent

import { ImageUploadContent } from "@/components/ImageUploadContent";

// Rendered inside the block settings panel of the builder
<ImageUploadContent
  url={currentImageUrl}
  onSubmit={(url: string) => handleUrlChange(url)}
/>

A controlled React component used within the builder's block settings to let users pick or upload an image. Use it when adding a new block type that contains an image property, or when you need to expose an image URL field inside any settings form panel.

vitest project config (exported from vitest.config.ts)

import { defineConfig } from "vitest/config";
import { fileURLToPath } from "node:url";

export default defineConfig({
  root: fileURLToPath(new URL(".", import.meta.url)),
  test: {
    projects: ["packages/**/vitest.config.{ts,mts}"],
    globalSetup: ["./packages/config/src/tests/globalSetup.ts"],
  },
});

The root Vitest configuration delegates test discovery to each package's own vitest.config.ts. Reference this pattern when adding a new package: create a vitest.config.ts in the package root and it will be picked up automatically without editing the root config.

ImageUploadContent (re-export barrel)

// apps/builder/src/components/ImageUploadContent/index.tsx
export { ImageUploadContent } from "./ImageUploadContent";

Barrel index that re-exports the component from its implementation file. When you add new builder UI components, follow this single-export barrel convention so tree-shaking works correctly with Next.js.

Working examples

Scenario - Embedding ImageUploadContent in a custom block settings panel

You are adding a "Hero Image" block to the builder. The block settings panel needs an image picker.

import React, { useState } from "react";
import { ImageUploadContent } from "@/components/ImageUploadContent";

interface HeroImageSettings {
  imageUrl: string;
}

interface Props {
  settings: HeroImageSettings;
  onSettingsChange: (updated: HeroImageSettings) => void;
}

export function HeroImageSettingsPanel({ settings, onSettingsChange }: Props) {
  const [url, setUrl] = useState(settings.imageUrl);

  function handleSubmit(newUrl: string) {
    setUrl(newUrl);
    onSettingsChange({ imageUrl: newUrl });
  }

  return (
    <div style={{ padding: "16px" }}>
      <label style={{ fontWeight: 600 }}>Hero image</label>
      <ImageUploadContent url={url} onSubmit={handleSubmit} />
    </div>
  );
}

Scenario - Running the full builder in Docker for a self-hosted environment

You want to run the builder and viewer together with a local Postgres instance.

# From source/
docker compose -f docker-compose.yml up --build

// Verify connectivity from a Node health-check script
import { createConnection } from "node:net";

function checkPort(host: string, port: number): Promise<boolean> {
  return new Promise((resolve) => {
    const socket = createConnection({ host, port }, () => {
      socket.destroy();
      resolve(true);
    });
    socket.on("error", () => resolve(false));
  });
}

async function main() {
  const builderReady = await checkPort("localhost", 3000);
  const viewerReady = await checkPort("localhost", 3001);
  console.log({ builderReady, viewerReady });
}

main();

Scenario - Adding a new package and wiring it into the Vitest workspace

You have created packages/my-feature/ and need tests discovered automatically.

// packages/my-feature/vitest.config.ts
import { fileURLToPath } from "node:url";
import { defineConfig } from "vitest/config";

export default defineConfig({
  root: fileURLToPath(new URL(".", import.meta.url)),
  test: {
    environment: "node",
    include: ["src/**/*.test.ts"],
  },
});

// packages/my-feature/src/greet.ts
export function greet(name: string): string {
  return `Hello, ${name}`;
}

// packages/my-feature/src/greet.test.ts
import { describe, expect, it } from "vitest";
import { greet } from "./greet";

describe("greet", () => {
  it("returns greeting", () => {
    expect(greet("Typebot")).toBe("Hello, Typebot");
  });
});

Run from the workspace root:

bun run test
# Vitest picks up packages/my-feature/vitest.config.ts automatically

File walkthrough

• .agents/ - Skill markdown files consumed by AI agents for standardized commit messages, UI patterns, model updates, and animation guidelines.
• .claude/ - launch.json configures how the Claude assistant is invoked within the repo context.
• .codex/environments/environment.toml - Declares the Codex sandbox environment spec for automated coding tasks.
• .github/workflows/ - CI pipelines: typechecking, releases, Docker builds, npm publishes for typebot-js and typebot-react, stale-issue management.
• .vscode/ - Workspace-scoped settings including i18n-ally custom framework config for translation key detection.
• .zed/ - Zed editor project-level settings.
• apps/builder/ - The Next.js builder application; contains src/ (pages, components, features), public/ (static assets, templates), and Next/PostCSS config.
• apps/docs/ - Documentation site (separate Next.js or static-site app).
• apps/landing-page/ - Public marketing site for typebot.io.
• apps/viewer/ - Next.js chatbot viewer/runtime served to end-users at a separate domain.
• packages/ - All shared logic: Prisma schema, Zod schemas, block definitions, email templates, config, test utilities.
• biome.json - Single config for Biome linting and formatting across the entire monorepo.
• bunfig.toml - Bun-specific registry and workspace settings.
• docker-compose*.yml - Three compose files: production, development (with hot reload), and CI build.
• nx.json - Defines task dependencies and caching for the Nx build system.
• tsconfig.base.json - Shared path aliases used by all apps and packages.
• vitest.config.ts - Root test config delegating to per-package configs via the projects glob.

Common pitfalls and fixes

• Bun vs Node mismatch: The repo is optimized for Bun; using npm or yarn may fail on workspace symlinks. Fix: install Bun (curl -fsSL https://bun.sh/install | bash) and use bun install.
• Missing ENCRYPTION_SECRET: The builder will crash at startup without a 32-character encryption secret. Fix: set ENCRYPTION_SECRET=$(openssl rand -hex 16) in .env.local.
• Prisma client not generated: Imports from @prisma/client fail with "module not found". Fix: run bunx prisma generate --schema packages/prisma/schema.prisma before starting.
• NEXT_PUBLIC_VIEWER_URL mismatch: Embedded bots in the builder preview silently fail if this var points to the wrong port. Fix: ensure it matches the actual port the viewer dev server binds to (default 3001).
• Nx cache stale across branches: Task outputs from another branch can serve wrong artifacts. Fix: run bunx nx reset to clear the local cache.
• TypeScript path aliases not resolving in tests: Vitest does not read tsconfig paths by default. Fix: add vite-tsconfig-paths plugin to each package's vitest.config.ts.

Vibe-coding prompt template

I have purchased the Typebot Builder monorepo source block. The source lives
in ./source/ relative to my project root. I also have USAGE.md open.

The upstream package is @typebot.io/root@3.16.1.

Please help me integrate this into my existing project step by step:

1. Read USAGE.md fully before taking any action.
2. Identify which app or package inside source/ is relevant to my goal: [DESCRIBE YOUR GOAL].
3. Install only the dependencies listed in USAGE.md § "Required dependencies"
   that are not already in my package.json.
4. Wire the TypeScript path aliases from source/tsconfig.base.json into my
   tsconfig.json without breaking my existing paths.
5. Set up the required environment variables from USAGE.md § "Project setup".
6. Show me a minimal working code snippet that imports from source/ and
   achieves [DESCRIBE YOUR GOAL], using only exports confirmed in USAGE.md
   § "Public API".
7. If you need to create new files, place them in src/ and follow the barrel
   export pattern shown in USAGE.md.
8. Do not invent APIs. If something is not in USAGE.md or visible in source/,
   ask me before assuming it exists.

License and credit

Typebot is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See source/LICENSE for the full license text. Self-hosted deployments must publish any modifications under the same license.

Upstream repository and package: https://github.com/baptisteArno/typebot.io / @typebot.io/root@3.16.1.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Flowise Visual AI Agent Builder and Orchestrator

SaaS, AI & Subscription Products

Free