📖 Reading: README Installation Section

Reading version requirements — >= means "at least this version"

The notation Node.js >= 18.0.0 is a mathematical inequality: your Node version must be greater than or equal to 18.0.0. Node 16.20.0 is less than 18.0.0, so it does not satisfy this requirement.

Why the minimum exists: Node 18 introduced or stabilised APIs the project depends on — commonly: the Fetch API (native), --experimental-vm-modules, updated crypto module, or performance improvements. The project author tested and supports only 18+. On 16, you might encounter:

• Install-time errors (npm install fails due to a native module requiring a newer V8)
• Runtime crashes on API calls that don't exist in Node 16
• Subtle behavioural differences that produce incorrect output without clear error messages

Understanding the parenthetical:

• "LTS recommended" → LTS (Long Term Support) versions receive security and bug fixes for ~3 years. For production, always prefer an LTS version (even-numbered: 18, 20, 22) over a Current release (odd-numbered: 19, 21).
• "20.x tested" → The maintainers specifically ran the test suite against Node 20. This doesn't mean 20 is required — it means it's verified to work.

How to check and manage Node versions: Use node --version to check. Use nvm (Node Version Manager) or fnm (Fast Node Manager) to switch between versions easily. Most projects include a .nvmrc or .node-version file with the recommended version — run nvm use in the project directory to switch automatically.

The .env pattern — separating configuration from secrets

This is one of the most important security practices in web development, codified as Factor III of the Twelve-Factor App methodology: "Store config in the environment."

Why .env is NOT committed to Git:

• It contains real credentials: database passwords, API keys, secret tokens
• Once committed to a public (or even private) repo, secrets are exposed — Git history is permanent
• Even a brief accidental commit can result in credential rotation requirements and potential breaches
• CI/CD systems, different developers, and different environments (dev/staging/prod) all need different values

How the pattern works:

• .env.example (committed to git): Shows which variables exist, with placeholder or safe example values. Documentation in code form.
• .env (git-ignored via .gitignore): Your local copy with real values. Never leaves your machine via git.

The instruction "fill in your values" means: open the copied .env file and replace placeholders like DATABASE_URL=postgresql://user:password@host/db with your actual connection string.

The "At minimum" qualifier: "At minimum, set DATABASE_URL and SECRET_KEY" tells you which variables are required vs optional. This implies other variables in .env.example are optional (they may have defaults built into the application code). Start with just the required ones, then add optional ones if you need specific features.

Common mistake: Forgetting to copy .env.example to .env and running npm run dev directly → the app fails with "missing environment variable" errors that look cryptic until you realise .env doesn't exist.

Reading "optional" prerequisites — conditional requirements

The phrase "optional — required only if enabling the job queue feature" is a conditional prerequisite. The README is telling you: Redis is not needed for the core app, but it IS needed for this specific feature.

Why the silent failure pattern occurs: Well-designed applications often degrade gracefully when optional dependencies are missing:

• Instead of crashing on startup, the app starts normally — job queue unavailable is not a fatal error for the main functionality
• When a job is submitted, the application may log a warning, silently drop the job, or return a success response while never actually processing the work
• This is often the correct design choice, but it makes debugging harder when the developer doesn't know Redis is required for that feature

How to diagnose this:

1. Check the application logs for any Redis-related warnings (e.g., "Could not connect to Redis at localhost:6379")
2. Run redis-cli ping — if Redis isn't running, this will fail with a connection error
3. Verify REDIS_URL or equivalent is set in your .env file

Reading README installation sections systematically:

• Read ALL prerequisites before starting installation — not just the "Quick Start" steps
• Note which prerequisites are conditional and which features they unlock
• Map out: "If I want feature X, I need to set up dependency Y"

The "optional" qualifier is not "you will never need it" — it means "not required for basic installation." Feature-level requirements are just as real as global requirements; they're deferred to the point of use rather than enforced at install time.