> ## 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.

# Usage Guide

> Learn how to import and use your synced ReadOnly files

## Basic Usage

After running `bunx readonly sync`, your files are available for import:

```typescript theme={null}
import { documents, config, redirects } from "@readonlystore/client";

console.log(documents.title);
console.log(config.apiUrl);
console.log(redirects["/old-path"]);
```

<Check>All imports are fully typed with IntelliSense support!</Check>

***

## Type Safety

ReadOnly automatically generates TypeScript types by introspecting your JSON files.

### Example

Given this JSON file named `config`:

```json theme={null}
{
	"apiUrl": "https://api.example.com",
	"timeout": 5000,
	"retries": 3,
	"features": {
		"darkMode": true,
		"analytics": false
	},
	"endpoints": ["/users", "/posts", "/comments"]
}
```

ReadOnly generates this type:

```typescript theme={null}
export declare const config: {
	apiUrl: string;
	timeout: number;
	retries: number;
	features: {
		darkMode: boolean;
		analytics: boolean;
	};
	endpoints: string[];
};
```

### IntelliSense

Your editor will provide:

* Auto-completion for all properties
* Type checking
* Inline documentation
* Go-to-definition support

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/readonly/images/intellisense-example.png" alt="IntelliSense example" />
</Frame>

***

## Import Patterns

### Named Imports

Import specific files:

```typescript theme={null}
import { documents } from "@readonlystore/client";
import { config } from "@readonlystore/client";
import { redirects } from "@readonlystore/client";
```

### Wildcard Import

Import all files at once:

```typescript theme={null}
import * as readonly from "@readonlystore/client";

console.log(readonly.documents);
console.log(readonly.config);
```

### Re-exporting

Re-export for use throughout your app:

```typescript theme={null}
// lib/readonly.ts
export { documents, config, redirects } from "@readonlystore/client";

// elsewhere in your app
import { documents } from "@/lib/readonly";
```

***

## Common Use Cases

### 1. Configuration

Store app configuration in ReadOnly:

```typescript theme={null}
import { config } from "@readonlystore/client";

const api = axios.create({
	baseURL: config.apiUrl,
	timeout: config.timeout,
});
```

### 2. Content Management

Manage blog posts or documentation:

```typescript theme={null}
import { posts } from "@readonlystore/client";

export function BlogList() {
  return (
    <div>
      {posts.items.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  );
}
```

### 3. Redirects

Handle URL redirects:

```typescript theme={null}
import { redirects } from "@readonlystore/client";

export function middleware(request: Request) {
	const path = new URL(request.url).pathname;
	const redirect = redirects[path];

	if (redirect) {
		return Response.redirect(redirect, 301);
	}
}
```

### 4. Feature Flags

Manage feature flags:

```typescript theme={null}
import { features } from "@readonlystore/client";

export function App() {
  return (
    <div>
      {features.darkMode && <DarkModeToggle />}
      {features.analytics && <Analytics />}
    </div>
  );
}
```

### 5. Reference Data

Store reference data like countries, currencies, etc:

```typescript theme={null}
import { countries } from "@readonlystore/client";

export function CountrySelect() {
  return (
    <select>
      {countries.map(country => (
        <option key={country.code} value={country.code}>
          {country.name}
        </option>
      ))}
    </select>
  );
}
```

***

## Framework Examples

### Next.js

```typescript theme={null}
// app/page.tsx
import { documents } from "@readonlystore/client";

export default function Home() {
  return (
    <div>
      <h1>{documents.title}</h1>
      <p>{documents.description}</p>
    </div>
  );
}
```

### Express

```typescript theme={null}
// server.ts
import express from "express";
import { config } from "@readonlystore/client";

const app = express();

app.listen(config.port, () => {
	console.log(`Server running on port ${config.port}`);
});
```

### Remix

```typescript theme={null}
// app/routes/_index.tsx
import { json } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";
import { documents } from "@readonlystore/client";

export const loader = () => {
  return json({ documents });
};

export default function Index() {
  const { documents } = useLoaderData<typeof loader>();
  return <h1>{documents.title}</h1>;
}
```

### Astro

```astro theme={null}
---
// src/pages/index.astro
import { documents } from "@readonlystore/client";
---

<html>
  <body>
    <h1>{documents.title}</h1>
    <p>{documents.description}</p>
  </body>
</html>
```

***

## Runtime vs Build Time

### Runtime Loading

Files are loaded at runtime from the cache:

```typescript theme={null}
// This loads from node_modules/.cache/readonly/documents.json
import { documents } from "@readonlystore/client";
```

### Build Time Sync

Sync during build to include files in your bundle:

```json package.json theme={null}
{
	"scripts": {
		"build": "readonly sync && next build"
	}
}
```

***

## File Updates

### Development

Use watch mode to automatically sync updates:

```bash theme={null}
bunx readonly dev
```

When you update files in the dashboard, they'll sync automatically.

### Production

Run watch mode alongside your app:

```json package.json theme={null}
{
	"scripts": {
		"start": "concurrently \"node server.js\" \"readonly dev\""
	}
}
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Keep files small">
    Individual files are limited to 10MB. Keep files focused and avoid large datasets.
  </Accordion>

  <Accordion title="Use descriptive names">
    Name your files descriptively: `config`, `features`, `redirects`, not `data1`, `file2`.
  </Accordion>

  <Accordion title="Validate JSON structure">
    Ensure your JSON is valid and follows a consistent structure. ReadOnly validates JSON objects only (no arrays or
    primitives at root).
  </Accordion>

  <Accordion title="Sync before build">
    Always run `readonly sync` before building for production to ensure files are up-to-date.
  </Accordion>

  <Accordion title="Use watch mode in development">
    Run `readonly dev` alongside your dev server to automatically sync changes.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/client/cli-reference">
    Learn about all available commands.
  </Card>

  <Card title="Configuration" icon="gear" href="/client/configuration">
    Customize cache and output directories.
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Installation and setup guide.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/help/troubleshooting">
    Common issues and solutions.
  </Card>
</CardGroup>