Skip to main content

Recommended Development Environment

This guide explains the recommended setup for developing with the Stentor conversational AI framework.

Prerequisites​

Node.js​

Stentor requires Node.js 12 or higher. The recommended version is specified in the .nvmrc file.

Recommended Version: Node.js 24.11.1

Supported Versions:

  • Node.js 12+ (minimum)
  • Node.js 14, 16, 18, 20, 22, 24.0.0+ (all tested and supported)

Node Version Manager (nvm)​

We recommend using nvm to manage Node.js versions:

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install the recommended Node.js version
nvm install 24.11.1

# Use the version specified in .nvmrc
nvm use

Package Manager​

Stentor uses Yarn as its package manager.

Required Version: 4.11.0

# Install Yarn globally
npm install -g yarn@4.11.0

# Verify installation
yarn --version

Initial Setup​

1. Clone the Repository​

git clone https://github.com/stentorium/stentor.git
cd stentor

2. Install Node.js​

The repository includes an .nvmrc file that specifies the Node.js version:

# Install and use the specified version
nvm install
nvm use

3. Install Dependencies​

yarn install

This installs all dependencies for the monorepo and all packages.

Repository Structure​

Stentor is organized as a monorepo managed by Lerna and Yarn Workspaces:

stentor/
�� packages/
   �� stentor/               # Main Assistant class
   �� stentor-models/        # Core interfaces/types
   �� stentor-runtime/       # Request/response engine
   �� stentor-handler*/      # Handler implementations
   �� stentor-channel/       # Channel abstractions
   �� stentor-response/      # Response building
   �� stentor-context/       # Conversation context
   �� stentor-storage/       # User data storage
   �� stentor-utils/         # Utility functions
   �� stentor-logger/        # Logging infrastructure
   �� ...other packages
�� api/                       # Generated API documentation
�� deploy/                    # Deployment scripts
�� website/                   # Docusaurus documentation site
�� .nvmrc                     # Node version specification
�� package.json              # Workspace configuration
�� lerna.json                # Lerna configuration
�� CLAUDE.md                 # Development guidance
�� README.md

Development Commands​

Building​

# Build all packages
yarn build

# Clean all build artifacts
yarn clean

# Clean node_modules from all packages
yarn clean:modules

Testing​

# Run tests across all packages
yarn test

# Test a specific package
cd packages/stentor-handler
yarn test

# Or using Lerna
yarn lerna run test --scope=stentor-handler

Note: Tests run with TZ=UTC timezone for consistency.

Linting​

# Lint TypeScript files across all packages
yarn lint

Version Management​

# Check for mismatched versions across packages
yarn version-check

# Check package licenses for compatibility
yarn license-check

Documentation​

# Generate API documentation from TypeScript
yarn docs

# Build documentation website
yarn docs:build

# Serve documentation locally
yarn docs:serve

# Deploy documentation to AWS
yarn docs:deploy

Lerna Commands​

# Access Lerna directly
yarn lerna

# Run a command in all packages
yarn lerna run build

# Run a command in specific package
yarn lerna run test --scope=stentor-models

# Clean and reset
yarn lerna clean

TypeScript Configuration​

Each package has its own tsconfig.json file:

  • Source files: Located in src/ directories
  • Compiled output: Goes to lib/ directories
  • Type definitions: Generated as .d.ts files

Compilation​

# Build all packages
yarn build

# Build specific package
cd packages/stentor-models
yarn build

Testing​

Stentor uses Mocha for testing with NYC for coverage.

Test Structure​

  • Test files follow the pattern: **/__test__/*.test.ts
  • Tests are located in __test__ directories within each package
  • All tests run with UTC timezone: TZ=UTC

Running Tests​

# All packages
yarn test

# Specific package
yarn lerna run test --scope=stentor-handler

# With grep filter
yarn --cwd packages/stentor-guards test --grep "isEventRequest"

Writing Tests​

import { expect } from "chai";
import { describe, it } from "mocha";

describe("MyFeature", () => {
  it("should work correctly", () => {
    // Your test
    expect(true).to.be.true;
  });
});

Environment Variables​

Studio Integration​

  • STUDIO_APP_ID - Your Studio application ID
  • STUDIO_TOKEN - Authentication token for Studio API
  • STUDIO_BASE_URL - Studio API endpoint (optional)

Development​

  • NODE_ENV - Set to "development" for development work
  • TZ - Timezone (set to UTC for testing)

Legacy (Deprecated)​

  • OVAI_TOKEN - Legacy OVAI token (deprecated)
  • OVAI_APP_ID - Legacy OVAI app ID (deprecated)

Git Workflow​

Branching​

  • Main branch: master
  • Feature branches: Create from master
  • Naming: Use descriptive names (e.g., feat/new-feature, fix/bug-description)

Commits​

Follow Conventional Commits:

# Examples
git commit -m "feat: add new channel support"
git commit -m "fix: resolve handler forwarding issue"
git commit -m "docs: update getting started guide"
git commit -m "chore: update dependencies"

Releases​

# Production release (creates tags, publishes to npm)
yarn release

# Prerelease (requires CIRCLE_BRANCH environment variable)
export CIRCLE_BRANCH=feature-branch-name
yarn release:pre

IDE Setup​

Recommended Extensions:

  • ESLint
  • TypeScript
  • Prettier
  • GitLens
  • Markdown All in One

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Other IDEs​

  • WebStorm: Works well with built-in TypeScript support
  • Sublime Text: Install TypeScript and ESLint packages
  • Atom: Install linter-eslint and atom-typescript

Code Quality​

ESLint​

Stentor includes ESLint configuration:

# Lint all files
yarn lint

# Lint specific package
cd packages/stentor-handler
yarn lint

TypeScript Strict Mode​

TypeScript is configured with strict type checking:

  • All types must be explicitly defined
  • No implicit any
  • Strict null checks enabled

Package Dependencies​

Workspace Dependencies​

Packages reference each other using workspace dependencies:

{
  "dependencies": {
    "stentor-models": "workspace:*",
    "stentor-utils": "workspace:*"
  }
}

External Dependencies​

Before adding new external dependencies:

  1. Check if similar functionality exists in existing packages
  2. Verify license compatibility using yarn license-check
  3. Consider bundle size impact

Common Development Tasks​

Adding a New Package​

  1. Create package directory: packages/my-new-package
  2. Add package.json with workspace references
  3. Add tsconfig.json extending base config
  4. Run yarn install to link workspace dependencies

Updating Dependencies​

# Update all dependencies (handled by Renovate bot)
# Or manually:
yarn upgrade-interactive

# Check for version mismatches
yarn version-check

Debugging​

Node.js Debugging:

# Run tests with debugger
node --inspect-brk ./node_modules/.bin/mocha

VS Code Launch Configuration:

{
  "type": "node",
  "request": "launch",
  "name": "Mocha Tests",
  "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
  "args": [
    "--timeout",
    "999999",
    "--colors",
    "${workspaceFolder}/packages/*/src/**/__test__/*.test.ts"
  ],
  "internalConsoleOptions": "openOnSessionStart"
}

Troubleshooting​

Build Failures​

# Clean and rebuild
yarn clean
yarn install
yarn build

Test Failures​

# Ensure UTC timezone
TZ=UTC yarn test

# Run specific test
yarn lerna run test --scope=stentor-handler -- --grep "specific test"

Dependency Issues​

# Clear all node_modules and reinstall
yarn clean:modules
yarn install

Performance Tips​

  1. Incremental Builds: Packages build incrementally; only changed packages rebuild
  2. Parallel Testing: Tests run in parallel across packages
  3. Selective Testing: Use --scope to test only affected packages

Next Steps​

Additional Resources​