page:guides:react router:configuration secrets

Configure Environment and Secrets for React Router

Summary

Configure environment variables and secrets for a React Router app on Ample. Values passed with --env or --env-file are stored encrypted and injected at runtime; the platform never prints them and ample.toml declares only variable names. The fixture proves delivery by reporting whether the secret is set without echoing it.

Resource Requirements

• primitive:compute

Infrastructure Requirements

• Compute: Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.

Prerequisites

• Code that reads configuration from the process environment
• The secret values at hand for --env or an env file
• An Ample account token with servers:write

Tested Configuration

• Template: node-22
• Runtime: node
• Size: s-1vcpu-1gb
• Install: npm install
• Build: npm run build --if-present
• Start: npm run start

Input Schema

{
  "additionalProperties": false,
  "properties": {
    "env": {
      "description": "Encrypted environment variables as KEY=value; secret values are never stored in ample.toml",
      "items": {
        "pattern": "^[A-Z][A-Z0-9_]*=.*$",
        "type": "string"
      },
      "maxItems": 50,
      "type": "array"
    },
    "name": {
      "description": "App name (lowercase, digits and dashes)",
      "maxLength": 63,
      "minLength": 1,
      "pattern": "^[a-z0-9-]+$",
      "type": "string"
    },
    "path": {
      "description": "Project directory to deploy, or one service name from ample.toml",
      "maxLength": 512,
      "minLength": 1,
      "type": "string"
    },
    "size": {
      "description": "VM size; omit to let Ample pick a runtime-safe size",
      "enum": ["s-1vcpu-256mb", "s-1vcpu-1gb", "s-1vcpu-2gb", "s-2vcpu-2gb", "s-2vcpu-4gb"],
      "type": "string"
    },
    "start": {
      "description": "Start command override when detection cannot infer it (Python apps pass one explicitly)",
      "maxLength": 512,
      "type": "string"
    }
  },
  "required": ["env", "name", "path"],
  "type": "object"
}

Workflow Steps

1. Declare, do not commit: In ample.toml declare SMTP_KEY = { secret = true } style entries; never put literal secrets in the manifest.
2. Pass values on deploy: Use --env KEY=value (repeatable) or --env-file .env.production; values are encrypted at rest and reused on redeploys. Command: ample deploy . --name --public --env CANARY_SECRET=...
3. Confirm without echoing: Expose a route (/config) that reports secret=set or secret=missing, never the value.
4. Verify: Fetch the live URL and run the success checks below. Command: ample logs --kind build

Examples

• React Router secret probe canary: /config reports secret=set for an --env value delivered encrypted. Source ref: tests/deploy-canaries/react-router-postgres-app

Success Checks

• App sees the configured variable without exposing it. Kind: http_get, Path: /config, Expect: secret=set

Limitations

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.

Cost Estimate

• Currency: USD
• Monthly Amount: 5.0
• Components:
  • App server: size s-1vcpu-1gb, quantity 1.0, monthly amount 5.0
• Note: Apps and managed databases auto-pause when idle; the estimate is the always-on monthly price of the tested sizes.