Local setup

Follow the local setup steps for KilatKoding on Windows, macOS, or Linux.

Prerequisites

The repository was verified with Node.js 24.4.1 and npm 11.4.2. In practice, a modern Node version compatible with Next.js 16 should also work, but those versions are the snapshot used by this repository as of March 19, 2026.

You also need:

• Git
• a code editor such as VS Code
• access to the repository or a project ZIP

Install tools by operating system

Windows

Use PowerShell or the terminal built into VS Code.

Quick setup with winget:

winget install Git.Git
winget install OpenJS.NodeJS.LTS

After installation, close and reopen your terminal. Make sure these commands work:

git --version
node --version
npm --version

macOS

If you use Homebrew:

brew install git node

Then verify:

git --version
node --version
npm --version

Linux

The example below uses Ubuntu or Debian. If you use another distro, switch to the equivalent package manager.

sudo apt update
sudo apt install -y git nodejs npm

Then verify:

git --version
node --version
npm --version

Run the project for the first time

1. Get the source code

   If you have repository access, clone it. If you received a ZIP, extract it into your working directory.

   git clone <your-repo-url>
   cd kilatkoding-src
   
2. Install dependencies

   Run:

   npm install
   
3. Create the local environment file

   On macOS or Linux:

   cp .env.example .env.local
   

   On Windows PowerShell:

   Copy-Item .env.example .env.local
   

   For local setup, keep your local secrets and overrides in .env.local. Next.js reads both .env and .env.local, but .env.local is the safest place for local-only changes.

4. Fill `.env.local`

   Use Environment variables as the reference for every variable. Do not guess env names. The repository already defines a clear structure.

5. Check readiness

   Run:

   npm run env:check
   

   This command reads .env and .env.local, then tells you which features are ready, which ones are in fallback mode, and which ones are intentionally disabled.

6. Start the app

   Run:

   npm run dev
   

   Then open http://localhost:3000.

   If you change env files while the dev server is already running, restart npm run dev so the latest values are picked up.

If you also want to run E2E tests

Install the Playwright browser once:

npx playwright install chromium

Then run:

npm run e2e

Signs that local setup worked

Check	Expected result
npm run env:check	No fatal errors for the features you left enabled
npm run dev	The dev server starts without crashing
http://localhost:3000	The landing page loads
Login or dashboard	Works if auth is enabled and Supabase is configured correctly

Most common local setup issues

• Node is too old or too new for a dependency.
• .env.local does not exist yet.
• Supabase env is still empty while auth remains enabled.
• Payments or AI are enabled without the env they require.
• Env values were changed, but the dev server was never restarted.

If one of those issues shows up, go to Troubleshooting.