Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Document environment variables centrally — `.env.example`, `env.validation.ts` and README config are scattered

Open
  • Is something wrong?
#208 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
45/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
nodejs, typescript
Domain
documentation, tooling

Research direction

Start by reading src/config/env.validation.ts to see how the schema is declared, then look at scripts/export-openapi.ts as a model for a generator script. Compare .env.example, .env.production.example and .env.secrets.template against the schema keys, and confirm .gitignore covers .env. Done means docs/ENVIRONMENT.md is generated by an npm run docs:env script, a CI check fails when a schema key is missing from .env.example, and the README links to the new doc.

Written by the indexing model from the issue text.

Description

documentation help wanted intermediate refactor

Problem

Environment variable knowledge is spread across four places that must be kept in sync manually:

  1. src/config/env.validation.ts — 507 lines, the largest config file, containing the validation schema
  2. .env.example
  3. .env.production.example
  4. .env.secrets.template
  5. README.md lines 237-252 ("Configuration & deployment"), which names a handful of variables inline

There is no single reference document, and nothing verifies that the three .env templates cover every key that env.validation.ts requires. A new required variable can be added to the validation schema with no corresponding template entry, and the failure mode is a boot-time crash for someone following the README.

Why it matters

Onboarding friction, and a real class of deployment bug. The README instructs contributors to copy .env.example → .env and populate it (line 105). If that file is incomplete relative to the validation schema, a fresh setup fails in a way that looks like a bug rather than a missing config key.

Suggested Direction

  1. Generate the docs. Write a script (scripts/, where export-openapi.ts and validate-openapi.ts already live) that imports the env.validation.ts schema and emits docs/ENVIRONMENT.md: variable name, type, required/optional, default, and a one-line description. Add it as npm run docs:env. This keeps the docs correct automatically as the schema changes.
  2. Add a CI check that every key in env.validation.ts appears in .env.example. This is the check that actually prevents the failure mode, and it is a small script.
  3. Reconcile the three templates. They presumably differ by environment; make the differences intentional and documented rather than accidental. Consider generating all three from one source of truth.
  4. Replace the README's inline config list with a link to docs/ENVIRONMENT.md, keeping only the deployment-relevant narrative (rate-limit tiers, Sentry) in place.

Constraints

  • Never commit real secrets. .env.secrets.template must stay a template — verify .gitignore covers .env before adding any generation step that reads env files.
  • The generation script must not print secret values, only names, types, and defaults. Redact anything that looks sensitive even in the template.
  • env.validation.ts is 507 lines — if a generator cannot introspect the schema cleanly, that itself is a reason to restructure the file into composable per-domain schemas (config, auth, database, observability). Consider that as a follow-up.

Acceptance Criteria

  • docs/ENVIRONMENT.md exists and is generated from env.validation.ts.
  • npm run docs:env regenerates it.
  • A CI check fails if a validation key is missing from .env.example.
  • All three .env templates are reconciled and their differences are documented.
  • README.md links to docs/ENVIRONMENT.md.
  • No secret values appear in any generated output.
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.