Skip to main content

​
Environment Variables

Configure the ReadOnly client using environment variables:

​
Required

READONLY_API_KEY (required) Your project API key from the ReadOnly dashboard. 
READONLY_API_KEY=ro_abc123...
Never commit this to version control. Use .env files.

​
Optional

READONLY_API_URL (optional, defaults to https://api.readonly.store) Custom API URL (useful for self-hosted instances). 
READONLY_API_URL=https://api.readonly.store
READONLY_CACHE_DIR (optional, defaults to .cache) Cache directory name (relative to node_modules/). 
READONLY_CACHE_DIR=.cache
Files will be cached in node_modules/.cache/readonly/ READONLY_OUTPUT_DIR (optional, defaults to _generated) Output directory for generated TypeScript files (relative to node_modules/). 
READONLY_OUTPUT_DIR=_generated
Types will be generated in node_modules/_generated/readonly/

​
Configuration Methods

Create a .env file in your project root:
.env
READONLY_API_KEY=ro_abc123...
READONLY_API_URL=https://api.readonly.store
Add .env to .gitignore:
.gitignore
.env
.env.local
.env.*.local

​
2. Shell Export

Export variables in your shell: 
export READONLY_API_KEY=ro_abc123...
export READONLY_API_URL=https://api.readonly.store

​
3. Inline Command

Prefix commands with environment variables: 
READONLY_API_KEY=ro_abc123... bunx readonly sync

​
4. CI/CD Secrets

For CI/CD pipelines, use your platform’s secret management: 
env:
  READONLY_API_KEY: ${{ secrets.READONLY_API_KEY }}

​
Directory Structure

The default directory structure: 
your-project/
├── node_modules/
│   ├── .cache/
│   │   └── readonly/           # Cached files (READONLY_CACHE_DIR)
│   │       ├── documents.json
│   │       └── config.json
│   └── _generated/
│       └── readonly/           # Generated types (READONLY_OUTPUT_DIR)
│           ├── index.js
│           ├── index.d.ts
│           ├── documents.d.ts
│           └── config.d.ts
├── .env                        # Environment variables
└── package.json

​
Customizing Directories

Change the cache and output directories:
.env
READONLY_CACHE_DIR=.my-cache
READONLY_OUTPUT_DIR=.my-generated
Result: 
node_modules/
├── .my-cache/
│   └── readonly/
└── .my-generated/
    └── readonly/
Changing these directories will affect import paths. Make sure to update your tsconfig.json if needed.

​
TypeScript Configuration

No special TypeScript configuration is required. The client uses standard node_modules resolution. However, if you want to add path aliases, you can configure tsconfig.json:
tsconfig.json
{
	"compilerOptions": {
		"paths": {
			"@readonly/*": ["node_modules/_generated/readonly/*"]
		}
	}
}
Then use: 
import { documents } from "@readonly/index";

​
Security Best Practices

Always use .env files and add them to .gitignore: bash .gitignore .env .env.local .env.*.local
Create separate projects for development, staging, and production: bash # Development READONLY_API_KEY=ro_dev_abc123... # Production READONLY_API_KEY=ro_prod_xyz789...
Regenerate API keys periodically from the dashboard: 1. Go to your project settings 2. Click “Regenerate API Key” 3. Update your environment variables
Store API keys in your CI/CD platform’s secret management: - GitHub Actions: Repository Secrets - GitLab CI: CI/CD Variables - CircleCI: Environment Variables

​
Production Configuration

​
Docker

Dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

# Set environment variables
ENV READONLY_API_KEY=${READONLY_API_KEY}

# Sync files during build
RUN npx readonly sync

CMD ["node", "server.js"]

​
Docker Compose

docker-compose.yml
services:
    app:
        build: .
        environment:
            - READONLY_API_KEY=${READONLY_API_KEY}
        command: sh -c "readonly dev & node server.js"

​
Kubernetes

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
    name: myapp
spec:
    template:
        spec:
            containers:
                - name: app
                  image: myapp:latest
                  env:
                      - name: READONLY_API_KEY
                        valueFrom:
                            secretKeyRef:
                                name: readonly-secrets
                                key: api-key

​
Next Steps

CLI Reference

Learn about all available commands.

Usage Guide

Learn how to import and use files.

Quickstart

Get up and running quickly.

Troubleshooting

Common issues and solutions.