> ## Documentation Index
> Fetch the complete documentation index at: https://docs.readonly.store/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
> Configure the ReadOnly client for your project
## Environment Variables
Configure the ReadOnly client using environment variables:
### Required
**`READONLY_API_KEY`** (required)
Your project API key from the ReadOnly dashboard.
```bash theme={null}
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).
```bash theme={null}
READONLY_API_URL=https://api.readonly.store
```
**`READONLY_CACHE_DIR`** (optional, defaults to `.cache`)
Cache directory name (relative to `node_modules/`).
```bash theme={null}
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/`).
```bash theme={null}
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:
```bash .env theme={null}
READONLY_API_KEY=ro_abc123...
READONLY_API_URL=https://api.readonly.store
```
Add `.env` to `.gitignore`:
```bash .gitignore theme={null}
.env
.env.local
.env.*.local
```
### 2. Shell Export
Export variables in your shell:
```bash theme={null}
export READONLY_API_KEY=ro_abc123...
export READONLY_API_URL=https://api.readonly.store
```
### 3. Inline Command
Prefix commands with environment variables:
```bash theme={null}
READONLY_API_KEY=ro_abc123... bunx readonly sync
```
### 4. CI/CD Secrets
For CI/CD pipelines, use your platform's secret management:
```yaml GitHub Actions theme={null}
env:
READONLY_API_KEY: ${{ secrets.READONLY_API_KEY }}
```
```yaml GitLab CI theme={null}
variables:
READONLY_API_KEY: $READONLY_API_KEY
```
```yaml CircleCI theme={null}
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:
```bash .env theme={null}
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`:
```json tsconfig.json theme={null}
{
"compilerOptions": {
"paths": {
"@readonlystore/*": ["node_modules/_generated/readonly/*"]
}
}
}
```
Then use:
```typescript theme={null}
import { documents } from "@readonlystore/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 Dockerfile theme={null}
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
```yaml docker-compose.yml theme={null}
services:
app:
build: .
environment:
- READONLY_API_KEY=${READONLY_API_KEY}
command: sh -c "readonly dev & node server.js"
```
### Kubernetes
```yaml deployment.yaml theme={null}
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
Learn about all available commands.
Learn how to import and use files.
Get up and running quickly.
Common issues and solutions.