Configuration

atoms.json

The atoms.json file is generated by vendor/bin/atoms init. It describes where your Atom code lives and the environments you deploy to.

{
    "project": "my-app",
    "paths": {
        "atoms": "app/Atoms",
        // DTOs or other shared code used on the Atom side and the App side:
        "shared": "app/Atoms/Shared"
    },
    "environments": {
        "production": {
            "worker_name": "my-app",
            "account_id": "",
            "debug_endpoints": false,
            "callback_url": "https://example.com/atoms/callback",
            "custom_domains": ["atoms.example.com"]
        },
        "staging": {
            "worker_name": "my-app-staging",
            "account_id": "",
            "debug_endpoints": true,
            "callback_url": "https://staging.example.com/atoms/callback"
        }
    }
}

Key	Required	Default
project Project slug, recorded in the build manifest	yes	—
paths.atoms Directory holding your Atom classes	yes	—
paths.shared Directory of code used on both the Atom side and the App side	no	<paths.atoms>/Shared
environments.<name>.worker_name Name of the Cloudflare Worker this environment deploys to	yes	—
environments.<name>.account_id Cloudflare account that owns the Worker	no	—
environments.<name>.callback_url URL where the Worker reaches your app for app() and dispatch()	no	—
environments.<name>.debug_endpoints Whether the Worker exposes its /debug routes	no	false
environments.<name>.custom_domains Hostnames the Worker answers on	no	[]

account_id is needed only when your Cloudflare credentials can reach more than one account. callback_url must use HTTPS, except for local development, where an HTTP URL on localhost, 127.0.0.1 or [::1] works too.

Environment variables

You can also set the Cloudflare API token, account_id and callback_url with the environment variables CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and ATOMS_CALLBACK_URL. In CI, set them as job variables, taking the API token from your secret store. A variable overrides the matching key in atoms.json; Environments lists the full order.

.env.atoms.<environment>

When you deploy or run atoms dev from your own machine, you can keep these variables in a file beside atoms.json named after the environment:

.env.atoms.production

CLOUDFLARE_API_TOKEN=…
ATOMS_CALLBACK_URL=https://my-tunnel.example.com/atoms/callback

The file is optional, and atoms init adds /.env.atoms.* to your .gitignore. Write one KEY=value per line, with optional quotes and # comments. A command reads only the file for the environment you pass to --env, and a variable set in your shell takes priority over it.

atoms-worker/wrangler.jsonc

The Worker scaffold command printed by atoms init creates atoms-worker/, including this Wrangler configuration file. It’s yours to edit: add logging, placement, limits and runtime vars at the top level, and they apply to every environment. Keep the keys marked RUNTIME-REQUIRED, which the Worker needs in order to load.

Settings that differ between environments go in atoms.json. atoms deploy and atoms dev combine the two using Wrangler’s generated configuration feature. They write a copy of this file with the selected environment’s Worker name, custom domains, callback URL and debug setting filled in, to atoms-worker/.wrangler/deploy/wrangler.json, alongside a config.json that tells Wrangler to use the copy. Wrangler prints “Using redirected Wrangler configuration” when it does. Both files are removed when Wrangler exits.

Define environments in atoms.json rather than in Wrangler’s env.<name> sections, and declare hostnames under custom_domains rather than as routes here. The generated copy leaves out both, and atoms deploy prints a notice when it finds routes in this file.

atoms-composer.json

atoms init also writes this file. It lists the Composer packages that ship inside the Atom, separate from your application’s own composer.json:

{
    "require": {
        "atoms/database-illuminate": "^0.6"
    }
}

The file accepts require and repositories, and each required package must be on the package allowlist. atoms build resolves the file and writes atoms-composer.lock beside it. Commit the lock file so every build installs the same versions.

Application settings

Your application needs two settings to call its Atoms:

• ATOMS_ENDPOINT is the URL of the deployed Worker: its https://<worker_name>.<subdomain>.workers.dev URL, or one of its custom domains. For a local Worker started by atoms dev, use http://127.0.0.1:8787.
• ATOMS_SHARED_SECRET is the same shared secret the Worker holds.

In Laravel, set both in .env, and config/atoms.php reads them:

ATOMS_ENDPOINT=https://atoms.example.com
ATOMS_SHARED_SECRET=…

In Symfony, read them in config/packages/atoms.yaml:

atoms:
    endpoint: '%env(ATOMS_ENDPOINT)%'
    shared_secret: '%env(ATOMS_SHARED_SECRET)%'

In plain PHP, pass endpoint and sharedSecret to AtomsConfig::fromArray(), as the plain-PHP example does.

For the optional settings, see the comments in Laravel’s published config/atoms.php, or the Symfony quickstart. Each environment’s callback_url in atoms.json should point at your application’s callback route, /atoms/callback by default.