Codicent App SDK

A comprehensive SDK for building AI-powered, chat-centric web applications with Codicent.

Codicent App SDK provides React components, hooks, and utilities to help you quickly build, customize, and deploy modern AI-powered apps. It is designed for rapid prototyping and production use, with built-in support for chat, markdown rendering, file uploads, and more.

🚀 Quick Start

1. Install the SDK

   npm install codicent-app-sdk
   # or
   yarn add codicent-app-sdk

2. Initialize the SDK

   import { initCodicentApp } from 'codicent-app-sdk';
   
   initCodicentApp({
     API_BASE_URL: 'https://codicent.com/',
     APP_NAME: 'my-app',
     // ...other config
   });

3. Use Components and Hooks

   import { useChat, Markdown } from 'codicent-app-sdk';
   // ...

Installation

From GitHub (Recommended)

npm install github:izaxon/codicent-app-sdk
# or
yarn add github:izaxon/codicent-app-sdk

From npm (Coming soon)

npm install @izaxon/codicent-app-sdk
# or
yarn add @izaxon/codicent-app-sdk

Usage

Initialization & Configuration

Before using the SDK, initialize it with your app’s settings:

import { initCodicentApp } from 'codicent-app-sdk';

initCodicentApp({
  API_BASE_URL: 'https://codicent.com/',
  APP_NAME: 'my-app',
  // ...other config
});

Configuration Options

Required:

API_BASE_URL: string // e.g. 'https://codicent.com/'
APP_NAME: string     // e.g. 'my-app'
APP_PREFIX: string   // e.g. 'myapp'
USER_PREFIX: string  // e.g. 'users'

Optional:

BUTTON_BORDER_RADIUS: string
BUTTON_BACKGROUND_COLOR: string
DEFAULT_LANGUAGE: string
SUBSCRIPTION_NEEDED: boolean
REALTIME_VOICE_MODEL: string // Voice model: "alloy", "shimmer", or "echo" (default: "alloy")
USE_REALTIME_SESSION_ENDPOINT: boolean // Use secure session endpoint (default: true)
// ...and more

For AI voice configuration and security, see the Voice Upgrade Guide.

CRUD Operations

The SDK provides comprehensive CRUD (Create, Read, Update, Delete) methods for managing structured data. For detailed documentation and examples, see:

📄 CRUD Method Usage Guide - Complete guide covering:

• CodicentService CRUD methods
• Usage patterns for project/task management and business records
• JavaScript library (codicentjs) API
• Best practices and complete examples

Example: Simple Chat App

import React from 'react';
import { CodicentService, useChat, Markdown, initCodicentApp } from 'codicent-app-sdk';

initCodicentApp({
  API_BASE_URL: 'https://codicent.com/',
  APP_NAME: 'my-app',
  APP_PREFIX: 'myapp',
  USER_PREFIX: 'users',
});

const App = () => {
  const codicentService = new CodicentService();
  const { messages, sendMessage } = useChat(codicentService);

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>
          <Markdown content={msg.content} />
        </div>
      ))}
      <button onClick={() => sendMessage('Hello world')}>Send</button>
    </div>
  );
};

Features

• React Components: Chat UI, Markdown, File Upload, Audio, and more
• Hooks: Chat state, authentication, localization, theme, and more
• AI Voice: Realtime voice AI with secure session endpoint support (see Voice Upgrade Guide)
• State Management: Efficient state machine with caching capabilities (see State Management Caching Improvements)
• Utilities: Helpers for app state, device, logging, and more
• TypeScript Support: Full typings for all exports
• Customizable: Theming and configuration options

Development

Building and Publishing

The SDK uses GitHub Actions to automate the build and publishing process:

1. On push to the main branch:

   • The package is automatically built
   • Documentation is deployed to GitHub Pages

2. When a new version tag is pushed (e.g., v0.3.12):

   • The package is built
   • A GitHub Release is created with the built package
   • The package is published to GitHub Packages

Release Process

To release a new version:

# 1. Update version in package.json
npm version patch|minor|major

# 2. Push changes with tags
git push --follow-tags

This will trigger the GitHub Actions workflow to create a release and publish the package.

Local Development

For local development:

# Install dependencies
npm install

# Run in development mode with watch
npm run dev

# Build locally
npm run build

The build process generates:

• CommonJS modules in dist/cjs
• ES modules in dist/esm
• TypeScript definitions

Testing Your Changes Locally

You can test SDK changes in your project:

# In the SDK directory
npm link

# In your project directory
npm link codicent-app-sdk

Documentation

Documentation is automatically deployed to GitHub Pages as part of the workflow when changes are pushed to the main branch.

For manual deployment:

# To manually build and copy artifacts to docs directory
npm run predeploy

# To manually deploy documentation
npm run deploy

Publishing to npm

To publish this package to npm:

1. Login to npm (if you haven't already):

   npm login

2. Build the package:

   npm run build

3. Publish to npm:

   npm publish --access public

Notes:

• Make sure the "name" field in package.json is set to codicent-app-sdk (no scope).
• The package name must be unique on npm.
• If you get a permissions error, ensure you are the owner of the package name on npm.

Documentation

For full documentation, visit our docs site.

Additional Documentation

• Voice Upgrade Guide - Complete guide for implementing and upgrading realtime voice AI features
• State Management Caching Improvements - Comprehensive analysis and strategies for optimizing state management performance through intelligent caching
• Implementation Guide - ✅ NEW! How to enable and use the state management caching system (now implemented!)

License

MIT © Codicent Inside AB

Fast Local SDK Testing Workflow

To quickly test changes in your local SDK with your app project, you can use npm link or a local file dependency. This avoids publishing to npm for every change.

Option 1: Using npm link

1. Build your SDK in watch mode (if needed):

   • If your SDK uses TypeScript or a bundler (like rollup), run it in watch mode so changes are rebuilt automatically.

     npm run build -- --watch

     Or for TypeScript:

     npx tsc --watch

2. Link your SDK globally: In your SDK root folder:

   npm link

3. Link your SDK in your app project: In your app project folder (the one that uses the SDK):

   npm link codicent-app-sdk

   (Replace codicent-app-sdk with the actual name in your SDK’s package.json if different.)

4. Test changes instantly: Now, when you make changes to your SDK and rebuild, your app will use the updated local version immediately—no need to publish or reinstall from npm.

5. Unlink when done: When you want to go back to using the npm-published version, run in your app project:

   npm uninstall codicent-app-sdk
   npm install codicent-app-sdk

Option 2: Using a Local File Dependency

1. In your app’s package.json, set the dependency to point to your local SDK folder:

   "dependencies": {
     "codicent-app-sdk": "file:../codicent-app-sdk"
   }

2. Run npm install in your app project.

Listening to codicent-log Events

You can listen for SDK log events of type codicent-log in your application. This is useful for debugging or integrating with your own logging system.

// Listen for log events
window.addEventListener('codicent-log', (event) => {
  // event.detail contains the log payload
  console.log('Codicent Log:', event.detail);
});

• The event is dispatched as a CustomEvent on the window object.
• The event.detail property contains the log data (such as level, message, and context).