AGENT SKILL

constants-configuration-pattern

Centralize all configuration constants — environment variables, cache keys — in the constants/ directory with strict naming and export conventions

License 许可
Apache-2.0
最近更新
2026-11-04
Stars
★ 41
Forks
0

01 前言 Front Matter

name
constants-configuration-pattern
description
Centralize all configuration constants — environment variables, cache keys — in the constants/ directory with strict naming and export conventions

03 SKILL.md 正文

Constants & Configuration Pattern

All configuration and constant values are centralized in constants/, organized by concern. No hardcoded strings in service or component files.

Key Change: API Endpoints No Longer Manual

With @repo/api-client, API endpoint URLs are no longer defined manually. The auto-generated SDK handles all URL construction using import.meta.env.VITE_API_URL (set via @t3-oss/env-core). See env.ts below.

For domains not covered by @repo/api-client, API endpoints can still be defined — see the legacy pattern at the end of this document.

Folder Structure

constants/
├── env.ts                ← Environment variables (required)
├── query-keys.ts         ← Cache keys (when using manual TanStack React Query)
└── index.ts              ← Optional re-exports

Environment Config (constants/env.ts)

Use @t3-oss/env-core with Zod schemas for validated, typed environment variables. Choose the example that matches your framework.

Vite / TanStack Start

Uses import.meta.env with VITE_ prefix:

// constants/env.ts
import { createEnv } from "@t3-oss/env-core";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().nonempty(),
    API_SECRET: z.string().nonempty()
  },

  clientPrefix: "VITE_",
  client: {
    VITE_API_URL: z.string().nonempty().url(),
    VITE_BASE_URL: z.string().nonempty().url(),
    VITE_APP_NAME: z.string().nonempty(),
    VITE_APP_VERSION: z.string().nonempty()
  },

  runtimeEnv: import.meta.env,
  emptyStringAsUndefined: true
});

Note: VITE_API_URL is consumed by @repo/api-client (Orval config reads import.meta.env.VITE_API_URL). No manual URL construction needed.

✅ DO — Use createEnv with Zod for validated env vars

✅ DO — Separate server and client blocks

✅ DO — Set emptyStringAsUndefined: true

✅ DO — Use VITE_ prefix for client variables

❌ DON'T — Access raw env vars directly in service/hook files

// ❌ DON'T — Raw access
const apiUrl = import.meta.env.VITE_API_URL;

// ✅ DO — Always import from ./env
import { env } from "[project-root]/constants/env";
const apiUrl = env.VITE_API_URL;

If Using Manual TanStack React Query (Non-api-client Domains)

Query keys go in constants/query-keys.ts. QueryClient setup and cache utilities belong in lib/query-client.ts — see the React Query Cache Utilities skill.

Legacy Pattern: Manual API Endpoints (Non-api-client Domains)

For domains not covered by @repo/api-client, define API endpoints manually:

// constants/api-endpoints.ts
import { env } from "./env";

const API_ENDPOINTS = {
  metadata: {
    app: `${env.VITE_API_URL}/app_metadata`
  },
  auth: {
    createAccount: `${env.VITE_API_URL}/auth/create_account`
  },
  users: {
    getMe: `${env.VITE_API_URL}/users/me`,
  },
} as const;

export default API_ENDPOINTS;

✅ DO — Legacy endpoint conventions

  • API_ENDPOINTS uses as const for type safety
  • Template literals for URL construction: `${env.VITE_API_URL}/path`
  • Only define endpoints for APIs not covered by @repo/api-client

❌ DON'T — Duplicate what api-client already provides

// ❌ DON'T — @repo/api-client already defines these URLs
const API_ENDPOINTS = {
  guides: {
    create: `${env.VITE_API_URL}/guides`,
    getAll: `${env.VITE_API_URL}/guides`,
  }
} as const;

Rules

✅ DO

  • Use createEnv from @t3-oss/env-core with Zod for env validation
  • Separate server and client env vars
  • Set emptyStringAsUndefined: true
  • Match clientPrefix to your framework's convention
  • Access env through env export, never directly from env globals
  • Let @repo/api-client handle all API URL construction for covered domains
  • Only define manual API endpoints for domains NOT covered by @repo/api-client
  • Query keys are enum members, not string literals
  • One config concern per file

❌ DON'T

  • Don't manually define API endpoints for domains covered by @repo/api-client
  • Don't access raw env vars in service, hook, or component files
  • Don't mix config concerns in the same file
  • Don't skip Zod validation on environment variables

04 同仓库更多 Skills

CliqRelay
CliqRelay/cliqrelay

typst

Typst document creation and package development. Use when: (1) Working with .typ files, (2) User mentions typst, typst.toml, or typst-cli, (3) Creating or using Typst packages, (4) Developing document templates, (5) Converting Markdown/LaTeX to Typst

★ 41
CliqRelay
CliqRelay/cliqrelay

shadcn

Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".

★ 41
CliqRelay
CliqRelay/cliqrelay

handoff

Compact the current conversation into a handoff document for another agent to pick up.

★ 41
CliqRelay
CliqRelay/cliqrelay

grilling

Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.

★ 41
CliqRelay
CliqRelay/cliqrelay

grill-me

A relentless interview to sharpen a plan or design.

★ 41
CliqRelay
CliqRelay/cliqrelay

dont-waffle

Use this skill when answering questions, explaining concepts, writing technical responses, reviewing code, or helping with development tasks. Communicate in clear, simple, standard English. Keep answers concise and focused, remove unnecessary filler and repetition, explain technical ideas in plain language, and structure information so it is easy to read and understand. When showing code, present it clearly with enough context for the developer to understand what it does and where it belongs.

★ 41