Configuration

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

1. Environment Variables (Recommended)

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 }}

variables:
    READONLY_API_KEY: $READONLY_API_KEY

environment:
    READONLY_API_KEY: ${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": {
			"@readonlystore/*": ["node_modules/_generated/readonly/*"]
		}
	}
}

Then use:

import { documents } from "@readonlystore/index";

Security Best Practices

Never commit API keys

Always use .env files and add them to .gitignore: bash .gitignore .env .env.local .env.*.local

Use different keys per environment

Create separate projects for development, staging, and production: bash # Development READONLY_API_KEY=ro_dev_abc123... # Production READONLY_API_KEY=ro_prod_xyz789...

Rotate keys regularly

Regenerate API keys periodically from the dashboard: 1. Go to your project settings 2. Click “Regenerate API Key” 3. Update your environment variables

Use CI/CD secrets

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.

Getting Started

Client

Help

Environment Variables

Required

Optional

Configuration Methods

1. Environment Variables (Recommended)

2. Shell Export

3. Inline Command

4. CI/CD Secrets

Directory Structure

Customizing Directories

TypeScript Configuration

Security Best Practices

Production Configuration

Docker

Docker Compose

Kubernetes

Next Steps

CLI Reference

Usage Guide

Quickstart

Troubleshooting

​Environment Variables

​Required

​Optional

​Configuration Methods

​1. Environment Variables (Recommended)

​2. Shell Export

​3. Inline Command

​4. CI/CD Secrets

​Directory Structure

​Customizing Directories

​TypeScript Configuration

​Security Best Practices

​Production Configuration

​Docker

​Docker Compose

​Kubernetes

​Next Steps

CLI Reference

Usage Guide

Quickstart

Troubleshooting

Environment Variables

Required

Optional

Configuration Methods

1. Environment Variables (Recommended)

2. Shell Export

3. Inline Command

4. CI/CD Secrets

Directory Structure

Customizing Directories

TypeScript Configuration

Security Best Practices

Production Configuration

Docker

Docker Compose

Kubernetes

Next Steps