Environment

The layer uses Varlock schemas to generate TypeScript types. The Docus Plus layer itself does not validate environment. A recommended setup is to keep the environment contract in the repository and use Varlock to load secret values from a remote secret storage during local development, CI and deployment.

This guide assumes the consuming project has copied the envs/ directory from the layer. Keep the schema and profile files in the same directory configured by package.json:

{
  "varlock": {
    "loadPath": "./envs/"
  }
}

Add the Vite integration

Install the integration in the consuming project:

pnpm add -D varlock @varlock/vite-integration

Add the plugin to the consumer's Nuxt configuration:

import { varlockVitePlugin } from "@varlock/vite-integration";

export default defineNuxtConfig({
  vite: {
    plugins: [varlockVitePlugin({ ssrInjectMode: "auto-load" })]
  }
});

auto-load makes the built server load the validated environment produced by Varlock. This is useful for a Node server deployment where the runtime can access the profile files. Run Nuxt as you would normally, but Varlock now loads and validates the environment in development, type generation, and production:

pnpm dev
pnpm build

The starter already contains a commented configuration example in nuxt.config.ts. Uncomment it when testing this integration locally.

For a deployment where the built artifact cannot read profile files at runtime, choose an injection mode intentionally. Read the Varlock Vite integration guide before using a mode that embeds resolved secrets in the build output. For a non-static Cloudflare Worker, use the platform-specific integration instead of bundling secrets with a plain Vite plugin.

Connect Proton Pass

Install and authenticate the official Proton Pass CLI, then add the Varlock plugin to the consumer's schema. The plugin resolves pass:// references through the CLI:

pnpm add -D @varlock/proton-pass-plugin

Add this near the top of envs/.env.schema:

# @plugin(@varlock/proton-pass-plugin)
# @initProtonPass(personalAccessToken=$PROTON_PASS_PERSONAL_ACCESS_TOKEN)

Then map application variables to fields in a Proton Pass vault. Use the vault, item, and field names from your own Proton Pass setup:

API_TOKEN=protonPass(pass://Docus%20Plus/Production/API_TOKEN)
MISTRAL_API_KEY=protonPass(pass://Docus%20Plus/Production/MISTRAL_API_KEY)

Do not put Proton Pass credentials in the schema or in a tracked profile. For CI, the recommended bootstrap variable is PROTON_PASS_PERSONAL_ACCESS_TOKEN. An already authenticated local CLI session can be used for local work instead. The Proton Pass plugin guide describes the alternative username, password, TOTP, and extra-password authentication options.

Populate each environment profile

Varlock selects a profile from APP_ENV. With the repository's loadPath, the conventional files are envs/.env.development, envs/.env.preview, envs/.env.production, and envs/.env.next. Start with the values that apply to every profile:

MODE=development
NITRO_PRESET=node-server
NUXT_PUBLIC_SITE_URL=http://localhost:3000

For preview or production, use the public HTTPS URL and select the deployment target explicitly:

MODE=production
NITRO_PRESET=node-server
NUXT_PUBLIC_SITE_URL=https://docs.example.com

The required application values are:

Add these conditionally:

• OPENAPI_SOURCE_TYPE and OPENAPI_SOURCE_LOCATION when API reference content is enabled.
• MAILCHIMP_API_KEY, MAILCHIMP_LIST, and MAILCHIMP_SERVER when newsletter signup is enabled.
• CLOUDFLARE_WORKER_NAME, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_CACHE_NAMESPACE_ID, and CLOUDFLARE_KV_API_TOKEN when NITRO_PRESET=cloudflare_module.
• REDIS_* variables when runtime caching uses Redis.

Use Varlock environments for profile selection and the layer README for the complete variable contract. Keep secret values in Proton Pass or the CI secret store; commit only the schema, safe profile defaults, and references.

Verify the setup

Validate and generate the environment types before starting Nuxt:

pnpm varlock load
pnpm env:typegen
pnpm varlock run -- nuxi dev

If a required value is missing, fix the selected profile or Proton Pass reference rather than silencing the validation error. In CI, make sure PROTON_PASS_PERSONAL_ACCESS_TOKEN is available before Varlock loads envs/.env.schema.