> ## 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

<Steps>
  <Step title="Install">
    <CodeGroup>
      ```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
      ```
    </CodeGroup>
  </Step>

  <Step title="Create an agent (ESM or CommonJS)">
    <Tabs>
      <Tab title="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>

      <Tab title="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');
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Note>
  Requires **Node.js 18 or later** (`engines.node >= 18`).
</Note>

***

## 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]
    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
```

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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');
    ```
  </Tab>
</Tabs>

<Info>
  Deno and Bun resolve the ESM entry automatically from the `import` condition.
</Info>

***

## Subpath Imports

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

<CodeGroup>
  ```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';
  ```
</CodeGroup>

| 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`)             |
| `./*`     | `praisonai/agent/simple` | Wildcard deep imports to any built module                         |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Prefer ESM imports in new projects" icon="arrow-up-right">
    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>

  <Accordion title="Bundle for the browser today — what works and what doesn't" icon="globe">
    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>

  <Accordion title="Verify your install with verify:dist" icon="circle-check">
    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>

  <Accordion title="Node version — 18 or later" icon="node-js">
    The package sets `engines.node >= 18`. The bundled `openai` dependency needs Node 18, so older runtimes are not supported.
  </Accordion>
</AccordionGroup>

<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.
</Warning>

***

## Related

<CardGroup cols={2}>
  <Card title="Node.js Agents" icon="node-js" href="/docs/js/nodejs">
    Build agents in Node.js with ESM or CommonJS
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/docs/sdk/typescript/index">
    Full TypeScript agent framework reference
  </Card>
</CardGroup>