Installation

Prerequisites

Before installing the SDK, ensure your environment meets these requirements.

Enable strict mode in your tsconfig.json:

{
  "compilerOptions": {
    "strict": true
  }
}

Install the Package

Add @monospace/sdk to your project.

npm install @monospace/sdk

pnpm add @monospace/sdk

yarn add @monospace/sdk

bun add @monospace/sdk

Add the Monospace SDK to Your Project

The fastest way to get started is the init command — an interactive setup wizard that creates your config file and optionally generates types immediately.

npx @monospace/sdk init

pnpm dlx @monospace/sdk init

yarn dlx @monospace/sdk init

bunx @monospace/sdk init

This will:

1. Prompt for your Monospace instance URL
2. Auto-detect the project identifier from the URL path
3. Ask for an output directory (default: ./src/generated/monospace)
4. Write a monospace.config.ts file
5. Optionally authenticate and generate types immediately

Configure Your Project

The SDK generator introspects your Monospace instance at build time and produces a fully typed TypeScript client tailored to your data model. This ensures the types in your code always stay in sync with your actual schema.

Create a monospace.config.ts (or monospace.config.js) file at your project root. This tells the generator where your instance lives and which project to introspect.

Remote Config

Point at a running Monospace instance:

import { defineConfig } from '@monospace/sdk/config'

export default defineConfig({
  url: 'https://example.monospace.io',
  project: 'blog',
  output: './src/generated/monospace',
})

Local Config

Generate types from a local OpenAPI spec file instead:

import { defineConfig } from '@monospace/sdk/config'

export default defineConfig({
  input: './local-schema.json',
  output: './src/generated/monospace',
})

Config Reference

A remote config uses url + project. A local config uses input. They cannot be mixed.

outputOptions controls the generated output:

Authenticate for Generation

Remote configs require authentication to fetch your schema. The CLI resolves credentials in this order:

1. --api-key <key> flag on the CLI command
2. MONOSPACE_API_KEY environment variable (.env files are loaded automatically)
3. OS keychain (stored via monospace-sdk login)

Using an Environment Variable

MONOSPACE_API_KEY=your-api-key-here

Using the Login Command

monospace-sdk login

This launches an interactive prompt where you can authenticate via API key or email/password. Credentials are stored in your OS keychain.

To remove stored credentials:

monospace-sdk logout

Generate Types from Your Schema

Run the generator to introspect your schema and produce a fully-typed client.

monospace-sdk generate

This produces a typed client you can import:

your-project/
├── src/
│   └── generated/
│       └── monospace/
│           └── index.ts
├── monospace.config.ts
├── package.json
└── tsconfig.json

Import the client factory from the generated output — not from the package directly:

import { createClient } from './src/generated/monospace';

{
  "scripts": {
    "monospace:generate": "monospace-sdk generate"
  }
}

Validate Your Setup

Check that your config, connection, and schema access are all working:

monospace-sdk validate

For remote configs, this verifies the config file, tests the connection (/api/ping), and confirms schema access using your credentials. For local configs, it checks the config and verifies the input file exists and contains valid JSON.

CLI Reference

The CLI binary is monospace-sdk. All commands:

Regenerate After Schema Changes

When you add, modify, or remove collections or fields in Studio, re-run the generator to keep your types in sync.

monospace-sdk generate

The generator overwrites the output file on each run. Do not edit it manually — your changes will be lost.

Next Steps

• Client Setup — create and configure the client
• Type System — understand how schema types map to TypeScript
• API Overview — understand the underlying REST API