> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Packaging & Bundlers

> Use praisonai in Node, browsers, React Native, and edge runtimes

praisonai ships both ESM and CommonJS builds, so it works out-of-the-box with modern bundlers and legacy Node projects alike.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "praisonai package"
        Src[📦 Source] --> Build{🔨 Build}
        Build --> CJS[⚙️ CJS<br/>dist/index.js]
        Build --> ESM[⚡ ESM<br/>dist/esm/index.js]
    end

    Node[🟢 Node<br/>require] --> CJS
    Bundlers[🌐 Bundlers<br/>Vite / Webpack / Metro] --> ESM
    TSApp[📘 TS / ESM App<br/>import] --> ESM

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    classDef consumer fill:#8B0000,stroke:#7C90A0,color:#fff

    class Src input
    class Build process
    class CJS,ESM output
    class Node,Bundlers,TSApp consumer
```

## Quick Start

**1. Install**

```bash npm theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
npm install praisonai
```

```bash yarn theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
yarn add praisonai
```

**2. Create an agent (ESM or CommonJS)**

> [tab] ESM
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> agent.start('Write a movie script about a robot in Mars');
> ```

> [tab] CommonJS
>
> ```javascript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> const { Agent } = require('praisonai');
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> agent.start('Write a movie script about a robot in Mars');
> ```

> [!NOTE]
>
> Requires **Node.js 18 or later** (`engines.node >= 18`).

***

## How It Works

The `package.json` entry points tell each runtime and bundler which build to load.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Import[import] --> ESMEntry[dist/esm/index.js]
    Require[require] --> CJSEntry[dist/index.js]
    Types[TypeScript] --> Dts[dist/index.d.ts]

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Import,Require,Types input
    class ESMEntry,CJSEntry,Dts output
```

`import` resolves to the ESM build, `require` resolves to the CJS build, and TypeScript reads the shared type declarations — no configuration needed on your side.

| Field | Value | What it does |
| - | - | - |
| `main` | `dist/index.js` | CommonJS entry for `require` |
| `module` | `dist/esm/index.js` | Hints bundlers at the ESM build |
| `types` | `dist/index.d.ts` | TypeScript declarations |
| `exports["."].import` | `./dist/esm/index.js` | ESM entry for `import` |
| `exports["."].require` | `./dist/index.js` | CJS entry for `require` |

The ESM build is produced by a small shim that rewrites relative specifiers, adds a `createRequire` banner for interop, and drops a `dist/esm/package.json` marked `{ "type": "module" }`.

***

## Using in Different Environments

Pick the entry point that matches where you run praisonai.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start([Where are you using praisonai?]) --> Q1{Runtime?}
    Q1 -->|Node.js server| Q2{ESM or CJS project?}
    Q1 -->|Browser / React Native| Deep[Use deep imports<br/>praisonai/agent/simple<br/>Agent + types]
    Q1 -->|Edge / Deno / Bun| ESMOnly[Use ESM entry<br/>import from 'praisonai']

    Q2 -->|"type: module"| ESMOnly
    Q2 -->|CommonJS| CJS[Use require<br/>const Agent = require'praisonai']

    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef answer fill:#10B981,stroke:#7C90A0,color:#fff
    classDef start fill:#6366F1,stroke:#7C90A0,color:#fff

    class Start start
    class Q1,Q2 question
    class Deep,ESMOnly,CJS answer
```

> [tab] Node.js (CommonJS)
>
> ```javascript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> const { Agent } = require('praisonai');
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> agent.start('Write a haiku about the ocean');
> ```

> [tab] Node.js (ESM)
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> agent.start('Write a haiku about the ocean');
> ```

> [tab] TypeScript
>
> ```json tsconfig.json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> {
>   "compilerOptions": {
>     "module": "esnext",
>     "moduleResolution": "bundler",
>     "target": "es2022"
>   }
> }
> ```
>
> ```typescript app.ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> agent.start('Explain quantum computing simply');
> ```

> [tab] Vite / Rollup / esbuild
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> await agent.start('Summarise the latest AI news');
> ```

> [tab] Next.js
>
> ```typescript app/api/agent/route.ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> export async function POST(req: Request) {
>   const { prompt } = await req.json();
>   const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
>   const result = await agent.start(prompt);
>   return Response.json({ result });
> }
> ```

> [tab] React Native (Metro)
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai/agent/simple';
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> agent.start('Suggest a name for my app');
> ```

> [tab] Deno / Bun
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
> agent.start('Write a limerick about coffee');
> ```

> [!NOTE]
>
> Deno and Bun resolve the ESM entry automatically from the `import` condition.

***

## Subpath Imports

Import from a subpath to load only the module you need.

```typescript Root barrel theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, Agents } from 'praisonai';
```

```typescript AI primitives theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { generateText, streamText } from 'praisonai/ai';
```

```typescript Tools theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { createTool, tool } from 'praisonai/tools';
```

```typescript Deep import theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai/agent/simple';
```

| Subpath | Import | Contents |
| - | - | - |
| `.` | `praisonai` | Full public API (`Agent`, `Agents`, `Workflow`, tools, providers) |
| `./ai` | `praisonai/ai` | AI SDK wrappers (`generateText`, `streamText`, `generateObject`) |
| `./tools` | `praisonai/tools` | Tool base classes and registry (`createTool`, `tool`) |
| `./agent/simple` | `praisonai/agent/simple` | The `Agent` class plus agent-related **type** exports (`SimpleAgentConfig`, `AgentTeamConfig`, `PraisonAIAgentsConfig`). The team-class **values** (`AgentTeam`, `PraisonAIAgents`, `Agents`) are not re-exported here — import those from `praisonai` or `praisonai/agent`. |

> [!NOTE]
>
> `praisonai/agent/simple` does not re-export `AgentTeam`, `PraisonAIAgents`, or `Agents` as runtime values. This keeps mobile and other webview bundles from statically pulling in the `agent/team` subsystem when they only need `Agent`. Import the team classes from `praisonai` or `praisonai/agent`. Type imports still work — `import type { AgentTeamConfig } from 'praisonai/agent/simple'` is erased at compile time and costs nothing at runtime.

***

## Best Practices

> [accordion] Prefer ESM imports in new projects
>
> Use `import { Agent } from 'praisonai'` for new code. ESM is the default for bundlers and edge runtimes, and it preserves `await import()` as a lazy chunk instead of forcing a synchronous `require()`.

> [accordion] Bundle for the browser today — what works and what doesn't
>
> The root barrel (`praisonai`) still pulls in the CLI and other Node-only code, so a raw `import 'praisonai'` in a browser or React Native bundle drags in Node built-ins. Use **deep imports** — for example `praisonai/agent/simple` — to keep browser and React Native bundles Node-safe.

> [accordion] Verify your install with verify:dist
>
> Contributors can run `npm run verify:dist` to confirm both the CJS and ESM entry points load in a real Node process before publishing.

> [accordion] Node version — 18 or later
>
> The package sets `engines.node >= 18`. The bundled `openai` dependency needs Node 18, so older runtimes are not supported.

> [!WARNING]
>
> The package is not marked `sideEffects: false`, so aggressive tree-shaking is limited today. Deep imports remain the best way to keep bundles small.

***

## Related

> [card] [Node.js Agents](https://praison.ai/docs/js/nodejs.md)
>
> Build agents in Node.js with ESM or CommonJS

> [card] [TypeScript SDK](https://praison.ai/docs/sdk/typescript/index.md)
>
> Full TypeScript agent framework reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.