Skip to content
Skills Library
Programming · Building & coding

setup-env-profiles

/setup-env-profiles

Sets up environment profiles (local, dev, test) with database connection strings and environment-specific configuration. Local uses Testcontainers, dev uses Supabase. Only prompts the user for the Supabase connection string. Use when the user asks to "set up environments", "configure profiles", "create .env files", "set up local/dev", or mentions environment profiles, environment configuration, or database connection setup.

Licence
Apache-2.0
Last repository change
25.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 25.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Sets up environment profiles (local, dev, test) with database connection strings and environment-specific configuration. Local uses Testcontainers, dev uses Supabase. Only prompts the user for the Supabase connection string. Use when the user asks to "set up environments", "configure profiles", "create .env files", "set up local/dev", or mentions environment profiles, environment configuration, or database connection setup.

Triggers from the description

set up environmentsconfigure profilescreate .env filesset up local/dev
Original author description

Sets up environment profiles (local, dev, test) with database connection strings and environment-specific configuration. Local uses Testcontainers, dev uses Supabase. Only prompts the user for the Supabase connection string. Use when the user asks to "set up environments", "configure profiles", "create .env files", "set up local/dev", or mentions environment profiles, environment configuration, or database connection setup.

How it works

  1. Instructions
  2. DO NOT
  3. Nexa Rules Gate
  4. Prerequisites
  5. Profiles and File Mapping
  6. Workflow
  7. Environment Profiles
Original SKILL.md headings · 271 lines, 1,359 words
SKILL.md preview
---
name: setup-env-profiles
description: >
  Sets up environment profiles (local, dev, test) with database connection strings
  and environment-specific configuration. Local uses Testcontainers, dev uses Supabase.
  Only prompts the user for the Supabase connection string. Use when the user asks to
  "set up environments", "configure profiles", "create .env files", "set up local/dev",
  or mentions environment profiles, environment configuration, or database connection setup.
---

# Setup Environment Profiles

## Instructions

Set up three environment profiles — **local**, **dev**, and **test** — each with its own
`.env` file and database connection string. Local and test both use Testcontainers;
dev uses Supabase.

This skill is **minimally interactive**. The only user input required is the Supabase
connection string for the dev profile.

## DO NOT

- Generate `docker-compose.yml` or any Docker infrastructure files
- Overwrite an existing `.env` file without showing the user what will change and asking for confirmation
- Store real credentials in committed files (all `.env*` files must be in `.gitignore`)
- Invent or guess database credentials — always ask the user

## Nexa Rules Gate

Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md`.

## Prerequisites

Check that `.gitignore` includes `.env*` entries. If not, add them before creating any
`.env` files:

```
.env
.env.*
.env.local
.env.development
.env.test
```

## Profiles and File Mapping

| Profile | File                 | Database                              | Purpose                                    |
|---------|----------------------|---------------------------------------|--------------------------------------------|
| local   | `.env.local`         | Testcontainers (dynamic at runtime)   | Local machine development                  |
| dev     | `.env.development`   | Supabase                              | Shared development / staging               |
| test    | `.env.test`          | Testcontainers (dynamic at runtime)   | Integration and e2e tests                  |

## Workflow

### Step 0: Consult Prisma Documentation

Before starting, use the **Context7 MCP tool** to fetch the latest Prisma documentation
on environment configuration and `prisma.config.ts`. This ensures the setup follows
the current Prisma conventions (e.g. config file format, env loading, `--config` flag usage).

Query Context7 for:
- `prisma.config.ts` configuration file setup and usage
- Prisma environment variables and `.env` file loading behavior

Use the documentation to inform decisions in subsequent steps — especially around
whether the project should use `prisma.config.ts` for env file resolution and how
Prisma CLI commands should reference the config.

### Step 1: Detect Existing Configuration

1. Check if Prisma is in use by looking for **any** of:
   - `prisma/schema.prisma`
   - `prisma.config.ts` (project root)
   - `prisma/prisma.config.ts`
2. If `prisma.config.ts` exists (at either location), note it as the **Prisma config path** —
   it will be used in later steps for CLI commands and env file resolution
3. Check if any `.env*` files already exist
4. If existing files are found, show the user which ones exist and ask whether to
   update them or skip

### Step 2: Local Profile (`.env.local`) — Auto-generated

This profile is **not interactive**. It uses Testcontainers, same as the test profile.

Generate `.env.local` with the following content:

```env
# =============================================================================
# Local Environment Profile (Testcontainers)
# =============================================================================
# DATABASE_URL is set dynamically by the dev script at startup.
# Testcontainers spins up a PostgreSQL container, runs migrations, and provides
# the connection string automatically.

# App
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Auth (local-only values — never use in production)
AUTH_SECRET="local-secret-do-not-use-in-production"
AUTH_URL="http://localhost:3000"
```

Only include `AUTH_SECRET` and `AUTH_URL` if the project uses next-auth / Auth.js.
Add any other environment variables the project needs with safe local-only defaults.

### Step 3: Dev Profile (`.env.development`) — Supabase

Ask the user for both URLs:

> **Supabase connection strings for the dev environment:**
>
> Prisma requires two connection URLs. Please provide both:
>
> 1. **Pooled URL** (`DATABASE_URL`) — used by your application at runtime.
>    Typically looks like:
>    `postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres`
>
> 2. **Direct URL** (`DIRECT_URL`) — used by Prisma for migrations and introspection.
>    Typically looks like:
>    `postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres`
>
> You can find both in your Supabase dashboard under **Settings → Database → Connection string**.

Wait for the user to provide both connection strings.

### Step 4: Test Profile (`.env.test`) — Auto-generated

This profile is **not interactive** — it is auto-generated for Testcontainers-driven
integration and e2e tests.

Generate `.env.test` with the following content:

```env
# =============================================================================
# Test Environment Profile (Testcontainers)
# =============================================================================
# DATABASE_URL is set dynamically by Testcontainers global setup at test runtime.
# Do not set DATABASE_URL here — it will be overridden by the test harness.

# App
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Auth (test-only values — never use in production)
AUTH_SECRET="test-secret-do-not-use-in-production"
AUTH_URL="http://localhost:3000"
```

Only include `AUTH_SECRET` and `AUTH_URL` if the project uses next-auth / Auth.js.
Add any other environment variables the project needs with safe test-only defaults.

Inform the user:

> Both **local** and **test** profiles use Testcontainers. `DATABASE_URL` is provided
> dynamically at runtime — by the dev script for local, and by Vitest/Playwright
> global setup for tests. PostgreSQL containers are started automatically, migrations
> are applied, and the connection string is injected into `process.env`.

### Step 5: Additional Environment Variables

Check if the project uses any of the following and, for the **dev profile only**,
ask the user to provide values if applicable:

- `NEXTAUTH_SECRET` / `AUTH_SECRET` (if next-auth is a dependency)
- `NEXTAUTH_URL` / `AUTH_URL` (if next-auth is a dependency)
- `NEXT_PUBLIC_APP_URL` (if referenced in the codebase)

For local and test profiles, use safe defaults automatically (as shown in Steps 2 and 4).
For any variables already present in existing `.env*` files, show current values
and ask whether to keep or update them.

### Step 6: Write Files

For the **dev** profile, generate the `.env` file with this structure:

```env
# =============================================================================
# Development Environment Profile (Supabase)
# =============================================================================

# Database
DATABASE_URL="<user_provided_pooled_url>"

# Direct connection URL (for Prisma migrations — bypasses connection pooling)
DIRECT_URL="<user_provided_direct_url>"

# App
# NEXT_PUBLIC_APP_URL="<if applicable>"

# Auth
# AUTH_SECRET="<if applicable>"
# AUTH_URL="<if applicable>"
```

Only include variables that are relevant to the project. Comment out optional
variables that were not provided rather than omitting them, so the user knows
they are available.

For the **local** and **test** profiles, write the files as defined in Steps 2 and 4.

### Step 7: Create `.env` Symlink

Create a `.env` symlink pointing to `.env.local` if one does not already exist:

```bash
ln -sf .env.local .env
```

This ensures tools that read `.env` by default (like Prisma) pick up the local profile.

### Step 8: Update Prisma Datasource (if needed)

Ensure the Prisma datasource includes `directUrl`. The location depends on the project setup:

- If `prisma.config.ts` exists: check whether the datasource `directUrl` is configured there
  (per the Context7 documentation fetched in Step 0). Update the config file accordingly.
- If `prisma/schema.prisma` is used (no `prisma.config.ts`): ensure the datasource block
  references `DIRECT_URL`:

```prisma
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}
```

If the project does **not** yet have a `prisma.config.ts` but the Context7 documentation
indicates it is the recommended approach for the project's Prisma version, suggest creating
one to the user and explain the benefits (centralized config, TypeScript support, env file
resolution). Do not create it without user confirmation.

### Step 9: Update CLAUDE.md

Append a `## Environment Profiles` section to the target project's `CLAUDE.md` so that
future sessions know which profiles exist and how they work.

1. If `CLAUDE.md` does not exist, create it
2. If a `## Environment Profiles` section already exists (check for `<!-- NEXA_ENV_PROFILES_CONFIGURED -->`),
   ask the user whether to overwrite or skip
3. Append the following section (fill in the actual values from the setup):

~~~markdown
## Environment Profiles

<!-- NEXA_ENV_PROFILES_CONFIGURED -->

| Profile | File               | Database                            |
|---------|--------------------|-------------------------------------|
| local   | `.env.local`       | Testcontainers (dynamic at runtime) |
| dev     | `.env.development` | Supabase                            |
| test    | `.env.test`        | Testcontainers (dynamic at runtime) |

- `.env` is a symlink to `.env.local` (default profile for tools that read `.env`)
- Local and test `DATABASE_URL` is injected at runtime by Testcontainers — do not set it in the `.env` files
- Dev `DATABASE_URL` uses Supabase connection pooling; `DIRECT_URL` is the direct connection for Prisma migrations
- Prisma config: [state whether `prisma.config.ts` is used and its location, or `schema.prisma` datasource block]
- All `.env*` files are in `.gitignore`
~~~

Do not remove or modify any other content in `CLAUDE.md`.

### Step 10: Summary

Present a summary of what was created:

```
## Environment Profiles Created

| Profile | File               | Database                                |
|---------|--------------------|-----------------------------------------|
| local   | .env.local         | Testcontainers (dynamic at runtime)     |
| dev     | .env.development   | Supabase                                |
| test    | .env.test          | Testcontainers (dynamic at runtime)     |

### Next Steps
- Run `npx prisma migrate dev` to apply migrations (add `--config <path>` if using `prisma.config.ts`)
- Verify the dev profile by running: `dotenv -e .env.development -- npx prisma db pull`
```

Versions

RepositoryScoreLicence
This page · nexadevapp/nexa-claude-skills-marketplace100Apache-2.0
nexadevapp/nexa-claude-skills-marketplace100Apache-2.0

Database snapshot: 13.11.2026 · package version 6a4823c50098 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100supabase-multi-env-setup
    Configure Supabase across development, staging, and production with separate projects, environment-specific secrets, and safe migration promotion. Use when setting up multi-environment deployments, isolating dev from prod data, configuring per-environment Supabase projects, or…
  • 100env-setup-wizard
    Set up environment variables, .env files, and configuration management. Use when configuring environment variables, creating .env files, or managing app configuration.
  • 100supabase-local-dev-loop
    Configure Supabase local development with the CLI, Docker, and migration workflow. Use when initializing a Supabase project locally, starting the local stack, writing migrations, seeding data, or iterating on schema changes. Trigger with phrases like "supabase local dev",…
  • 87supabase-test-harness
    Supabase test harness patterns including local Supabase setup, test user creation via Auth Admin API, RLS testing, migration testing (db_reset), seed sequences, rate limiting, and environment detection. Use when setting up Supabase testing infrastructure, creating test users,…
  • 100woo-setup
    Install WooCommerce, configure the development stack, and set up a local dev environment with WP-CLI, Docker, or wp-env. Use when setting up a new WooCommerce project or development environment.
  • 100auto-env
    Configure runnable development environments for repositories using repo inspection, targeted environment-variable discovery, Docker or local setup, and smoke-test evidence. Use this skill whenever the user asks to set up a repo, make a project runnable, configure environment…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.