Installation

Install the Tailor Platform SDK and set up your development environment

System requirements

Before installing the SDK, ensure your system meets these requirements:

• Node.js 22 or later - The SDK requires Node.js version 22 or higher
• npm, yarn, or pnpm - Any of these package managers will work
• Git - For version control (recommended)

Install Node.js

If you don’t have Node.js 22 or later installed:

1. Visit the official Node.js website
2. Download and install the latest LTS version (v22 or higher)
3. Verify your installation:

node --version
# Should output v22.0.0 or higher

npm --version
# Should output npm version

We recommend using a Node.js version manager like nvm or fnm to easily switch between Node.js versions.

Installation methods

Using create command (recommended)

The fastest way to get started is using the create command to scaffold a new project:

npm

npm create @tailor-platform/sdk -- --template hello-world my-app
cd my-app

npm 7+ requires -- before create-sdk options (for example, --template).

What this does:

1. Creates a new directory with your project name
2. Scaffolds a project using the selected template
3. Installs all necessary dependencies
4. Initializes a Git repository

Adding to an existing project

If you want to add the SDK to an existing Node.js project:

npm

npm install @tailor-platform/sdk

Then create a tailor.config.ts file in your project root:

tailor.config.ts

import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "my-app",
  db: { "main-db": { files: ["./db/*.ts"] } },
  resolver: { "main-resolver": { files: ["./resolvers/**/*.ts"] } },
});

Available templates

When using the create command, you can choose from these templates:

hello-world

Minimal starter project

Perfect for learning the basics. Includes:

• Simple resolver example
• Basic project configuration
• User database type

inventory-management

Full-featured sample application

Production-ready patterns. Includes:

• Complex TailorDB schemas
• Custom resolvers with business logic
• Event-driven executors
• Role-based permissions

testing

Testing patterns guide

Learn how to test your SDK code. Includes:

• Unit test examples with Vitest
• E2E test setup
• Mock patterns for TailorDB
• CI/CD integration

multi-application

Multi-app architecture

Share resources across apps. Includes:

• Multiple application setup
• Shared database patterns
• External resource references

Template usage

Specify a template with the --template flag:

npm create @tailor-platform/sdk -- --template inventory-management my-store

If you don’t specify a template, you’ll be prompted to choose one interactively.

Post-installation setup

Authenticate with Tailor Platform

After creating your project, authenticate with the Tailor Platform:

npx tailor-sdk login

This opens your browser to complete authentication and stores your credentials in ~/.config/tailor-platform/config.yaml.

Create a workspace

Every application needs a workspace. Create one with:

npx tailor-sdk workspace create --name my-workspace --region us-east-1

Available regions:

• us-east-1 - US East (N. Virginia)
• eu-west-1 - Europe (Ireland)
• ap-northeast-1 - Asia Pacific (Tokyo)

List your workspaces to get the workspace ID:

npx tailor-sdk workspace list

Save your workspace ID in an .env file:

TAILOR_PLATFORM_WORKSPACE_ID=your-workspace-id

This allows you to deploy without specifying --workspace-id every time.

Environment variables

Create an .env file in your project root for environment-specific configuration:

.env

TAILOR_PLATFORM_WORKSPACE_ID=your-workspace-id
TAILOR_PLATFORM_PROFILE=default

Available environment variables:

Variable	Description
TAILOR_PLATFORM_WORKSPACE_ID	Your workspace ID for deployments
TAILOR_PLATFORM_TOKEN	Authentication token (alternative to login)
TAILOR_PLATFORM_PROFILE	Workspace profile name
TAILOR_PLATFORM_SDK_CONFIG_PATH	Custom path to tailor.config.ts
EDITOR	Editor for opening generated files

Verify installation

Verify that everything is set up correctly:

1. Check SDK version

   npx tailor-sdk --version
   
2. Generate types

   npm run generate
   

   This should generate type definitions in your project without errors.

3. Build configuration

   npm run build
   

   This validates your TypeScript configuration and ensures there are no syntax errors.

Development dependencies

Required dependencies

When using generated types in your resolvers, executors, or workflows, install these dependencies:

npm

npm install --save-dev @tailor-platform/function-types

For database queries

If you’re using the Kysely type plugin for type-safe database queries:

npm

npm install @tailor-platform/kysely-type

IDE setup

Visual Studio Code

For the best development experience in VS Code:

1. Install the TypeScript extension
2. Enable TypeScript IntelliSense in your workspace settings
3. Add a tsconfig.json if not already present:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Other editors

The SDK works with any editor that supports TypeScript:

• WebStorm/IntelliJ IDEA - Built-in TypeScript support
• Vim/Neovim - Use coc-tsserver or nvim-lspconfig
• Sublime Text - Install LSP-typescript

Troubleshooting

Node.js version mismatch

If you see an error about Node.js version:

Error: The SDK requires Node.js 22 or later

Upgrade Node.js to version 22 or higher. If using nvm:

nvm install 22
nvm use 22

Permission errors on npm install

If you encounter permission errors during installation:

1. Don’t use sudo with npm
2. Configure npm to use a different directory:
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   
3. Add to your ~/.bashrc or ~/.zshrc:
   export PATH=~/.npm-global/bin:$PATH
   

Git initialization skipped

If git initialization is skipped:

• The project already exists within a git repository
• Git is not installed on your system
• Install git from git-scm.com to enable version control

Next steps

Now that you have the SDK installed:

Follow the quickstart

Create and deploy your first application

Learn about configuration

Understand how to configure your application