Skip to content
ACMS ACMS Docs

Local File Adapter

The local file adapter stores your content schema in a JSON file on disk. It is the default adapter for development and works without any external services.

Installation

Section titled “Installation”

The local file adapter is included in @useacms/cli:

Terminal window
npm install @useacms/cli

Configuration

Section titled “Configuration”
import { defineConfig } from '@useacms/client';
import { localFile } from '@useacms/cli/adapters';


export default defineConfig({
  dev: localFile({ path: './acms.json' }),
});

Options

Section titled “Options”
OptionTypeDefaultDescription
pathstring'./acms.json'Path to the JSON file relative to the project root

How It Works

Section titled “How It Works”

The local file adapter reads and writes directly to a JSON file on your filesystem. When the dev server starts, it:

  1. Creates the file if it doesn’t exist.
  2. Reads the current schema from the file.
  3. Writes field registrations and content updates back to the file.
  4. Watches the file for external changes (via chokidar).

Schema File Structure

Section titled “Schema File Structure”

The acms.json file contains both content and metadata:

{
  "hero": {
    "title": "Welcome to My Site",
    "subtitle": "Built with ACMS"
  },
  "contact": {
    "email": "hello@example.com"
  },
  "_meta": {
    "hero.title": {
      "type": "string",
      "lastAccessed": "2025-01-15T10:30:00.000Z"
    },
    "hero.subtitle": {
      "type": "string",
      "lastAccessed": "2025-01-15T10:30:00.000Z"
    },
    "contact.email": {
      "type": "string",
      "lastAccessed": "2025-01-15T10:30:00.000Z"
    }
  }
}

Use Cases

Section titled “Use Cases”
  • Development — The primary use case. Every ACMS project uses local file during development.
  • Simple static sites — If your content never changes after build, local file is sufficient even for production.
  • Prototyping — Quick setup with no external dependencies.

Version Control

Section titled “Version Control”

Since acms.json is a plain JSON file, it works naturally with Git:

Terminal window
# Track content changes
git add acms.json
git commit -m "Update hero content"

This gives you full version history of your content changes.

Limitations

Section titled “Limitations”
  • Not suitable for production sites that need runtime content updates.
  • No remote access — content lives only on the local machine.
  • No collaboration — only one person can edit at a time (unless the file is in a shared Git repo).

For production use, consider GitHub Gist, GitHub, Vercel Edge Config, or Cloudflare KV.

Next Steps

Section titled “Next Steps”