Installation

Prerequisites

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

Generated types, field autocomplete, and compile-time schema checks require TypeScript. The client runs without it — see Use the SDK from JavaScript.

With TypeScript, 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 exec monospace init

yarn run monospace init

bun run monospace init

This will:

1. Prompt for your Monospace instance URL
2. Auto-detect the workspace 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 workspace to introspect. The CLI loads either extension, so a .ts config works in a JavaScript project. The CLI reads the file with jiti; your bundler never sees it.

Remote Config

Point at a running Monospace instance:

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

export default defineConfig({
  url: 'https://example.monospace.io',
  workspace: '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 + workspace. 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 the login command)

Using an Environment Variable

MONOSPACE_API_KEY=your-api-key-here

Using the Login Command

npx @monospace/sdk login

pnpm exec monospace login

yarn run monospace login

bun run monospace 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:

npx @monospace/sdk logout

pnpm exec monospace logout

yarn run monospace logout

bun run monospace logout

Generate Types from Your Schema

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

npx @monospace/sdk generate

pnpm exec monospace generate

yarn run monospace generate

bun run monospace generate

This produces a typed client you can import:

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

Once types are generated, import the client factory from the generated output rather than from the package. The generated factory already knows your schema, so you pass no generic parameters:

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

{
  "scripts": {
    "monospace:generate": "monospace generate"
  }
}

Validate Your Setup

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

npx @monospace/sdk validate

pnpm exec monospace validate

yarn run monospace validate

bun run monospace 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 package installs a binary named monospace. Call it directly inside a package.json script. 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.

npx @monospace/sdk generate

pnpm exec monospace generate

yarn run monospace generate

bun run monospace generate

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

Use the SDK from JavaScript

The generator emits a TypeScript file. JavaScript projects skip generation and import createClient from the package instead.

import { createClient } from '@monospace/sdk';

const client = createClient({
  url: 'https://example.monospace.io',
  workspace: 'blog',
  apiKey: 'YOUR_API_KEY',
});

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'status'],
});

Collections and methods resolve at runtime, so filters, field selection, readFirst, relational writes, and error classes behave the same as with the generated client. You lose autocomplete and compile-time type errors.

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