Skip to main content

​
Get Started in 3 Steps

This guide will walk you through setting up ReadOnly in your project and syncing your first files.

​
Step 1: Create a Project

1

Sign up

Go to readonly.store and create an account.
2

Create a project

Click “New Project” and give it a name (e.g., “My Blog”).
3

Get your API key

Copy your project’s API key from the dashboard. It starts with ro_.

​
Step 2: Add Files

1

Add a file

Click “Add File” in your project dashboard.
2

Name your file

Give it a name like documents or config (alphanumeric, hyphens, and underscores only).
3

Paste JSON content

Add your JSON data. Must be a valid JSON object:
{
  "title": "Welcome to ReadOnly",
  "description": "Type-safe file sync",
  "version": "1.0.0"
}

​
Step 3: Install and Sync

1

Install the client

bash bun add @readonly/client # or npm install @readonly/client
2

Set your API key

Add your API key to a .env file in your project root:
READONLY_API_KEY=ro_your_api_key_here
Never commit your .env file to version control. Add it to .gitignore.
3

Sync your files

bunx readonly sync
This downloads your files and generates TypeScript types.
4

Use in your code

import { documents } from "@readonly/client";

console.log(documents.title); // "Welcome to ReadOnly"
console.log(documents.version); // "1.0.0"
Your files are now synced and fully typed!

​
Development Mode

For development, use watch mode to automatically sync changes: 
bunx readonly dev
Keep this running alongside your dev server. When you update files in the dashboard, they’ll sync automatically.

​
Production Usage

In production, run the CLI alongside your application: 
{
  "scripts": {
    "start": "concurrently \"node server.js\" \"readonly dev\""
  }
}

​
Next Steps

CLI Reference

Learn about all available commands.

Configuration

Customize cache and output directories.

Usage Guide

Learn how to use your synced files.

Troubleshooting

Common issues and solutions.
Security Note: Never commit your API key to version control. Use .env files and add them to .gitignore.