home / skills / next-friday / nextfriday-skills / nextfriday-nextjs

nextfriday-nextjs skill

safe

This skill enforces Next.js environment variable rules, ensuring client vars use NEXT_PUBLIC_ and no fallbacks for secure, predictable apps.

npx playbooks add skill next-friday/nextfriday-skills --skill nextfriday-nextjs

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
name: nextfriday-nextjs
description: Next Friday Next.js rules for environment variables and client components. Use when working with Next.js specific features.
user-invocable: false
---

# Next Friday Next.js

Rules specific to Next.js applications.

## Environment Variables

### Client Components

Client components must use `NEXT_PUBLIC_` prefix for environment variables.

```tsx
// Bad:
"use client";

const apiUrl = process.env.API_URL;
const secretKey = process.env.SECRET_KEY;

// Good:
"use client";

const apiUrl = process.env.NEXT_PUBLIC_API_URL;
const appName = process.env.NEXT_PUBLIC_APP_NAME;
const isDev = process.env.NODE_ENV === "development"; // NODE_ENV is OK
```

### No Fallback Values

Disallow fallback values for environment variables. Fail explicitly instead.

```typescript
// Bad:
const apiUrl = process.env.API_URL || "http://localhost:3000";
const timeout = process.env.TIMEOUT ?? "5000";

// Good:
const apiUrl = process.env.API_URL;
const timeout = process.env.TIMEOUT;

if (!apiUrl) {
  throw new Error("API_URL environment variable is required");
}
```

## Quick Reference

| Rule | Pattern |
| ---- | ------- |
| Client env vars | `NEXT_PUBLIC_` prefix required |
| No env fallbacks | Throw error if missing |

Overview

This skill documents Next Friday Next.js rules for handling environment variables and client components. It clarifies when environment variables must be exposed to the browser and enforces explicit failure for missing values. Use it to reduce accidental leaks of secrets and to make environment configuration deterministic across dev and production.

How this skill works

The skill inspects code for environment variable usage in client components and enforces the NEXT_PUBLIC_ prefix for any value accessed on the client. It also flags patterns that provide fallback values and recommends throwing errors or explicit checks instead, so missing configuration fails fast. The result is safer variable exposure and clearer runtime errors when configuration is incomplete.

When to use it

When building Next.js client components that read environment variables.
During code reviews to ensure secrets are not exposed to the browser.
When standardizing environment variable handling across a team or project.
When you want deterministic startup behavior and explicit failure on misconfiguration.

Best practices

Prefix any env var used in client components with NEXT_PUBLIC_.
Never supply fallback values for env vars; validate and throw if missing.
Keep secrets and server-only variables out of client components entirely.
Use NODE_ENV for environment checks when appropriate; it's safe in both client and server.
Validate required variables at startup to surface configuration errors early.

Example use cases

Detecting a client component that uses process.env.API_KEY and recommending NEXT_PUBLIC_API_KEY instead.
Finding code that uses process.env.FOO || 'default' and suggesting explicit validation plus an error throw.
Enforcing a project policy that only NEXT_PUBLIC_ vars appear in bundle-exposed code.
Adding pre-merge checks so missing env vars fail CI rather than producing silent runtime differences.

FAQ

Can I use fallback values for env vars in development only?

Avoid fallbacks altogether. Instead validate variables and throw a clear error so missing values are fixed consistently across environments.

Is NODE_ENV allowed in client components?

Yes. NODE_ENV is acceptable to read for environment checks; it does not expose secrets.