Skip to content

README.md

Latest commit

 

History

History
411 lines (273 loc) · 16.5 KB

README.md

File metadata and controls

411 lines (273 loc) · 16.5 KB

Getting Started with Local Development

This guide will help you set up your computer with a baseline for running most common applications written in Python, JavaScript, and TypeScript. By following these steps, you’ll set yourself up for headache free local development in 5 minutes.

Everything in this guide is a one time setup.

  • VSCode (Free and simple code interface)
  • WSL (To make life easier for Windows users)
  • Homebrew (To make life easier for macOS users)
  • uv (To make life easier with Python projects)
  • Bun (To make life easier with JavaScript and TypeScript projects)
  • Make (To run common project commands from a Makefile)
  • Git and GitHub (for built in version control and collaborating on code with others)
  • An AI coding assistant (Claude Code or Codex — the single biggest productivity boost in your setup)

1. Install VSCode (Visual Studio Code)

Download VSCode

  • Visit VSCode Download.
  • Choose your operating system (Windows, macOS, or Linux) and download the installer.

Install VSCode

  • Open the downloaded installer and follow the on-screen instructions.
  • When prompted, you can enable the options to add the VSCode executable to your PATH (on Windows), which makes it easier to open VSCode from the command line. I would just select checking any box that mentions PATH.

Launch VSCode

  • After installation, open VSCode.
  • Take a moment to familiarize yourself with the interface.
  • Notice on the left side the explorer button. This is where you can click to open repositories of code.
  • At the top of the screen are different tabs like File
  • Clicking File and then New Window will open a fresh VSCode screen

2. (Windows) Using Windows Subsystem for Linux (WSL)

If you use a Mac or Linux laptop, skip to 3.

If you’re on Windows, it is highly recommended to conduct all coding in WSL, the Windows Subsystem for Linux. WSL provides a full Linux environment inside Windows. Linux is an open source operating system that can run in an isolated environment on a Windows laptop. Using Linux makes it a lot easier for developers to work with open source software. It also comes with really nice quality of life benefits for coding.

Check your Windows version

  • You need Windows 10 (version 2004 or higher) or Windows 11 for WSL 2.

Install WSL

  1. Open your computer search bar and enter powershell

  2. When Windows PowerShell is shown, right click on it and select Run as Administrator, and click yes.

  3. Enter the command:

    wsl --install

    This command will enable the required components and download the latest Linux distribution. After it completes, try to open and close VSCode. It is possible you may need to restart your computer.

Use VSCode with WSL

  • Install the WSL extension in VSCode (search for "WSL" in the Extensions panel). Note
  • Then, you can open a folder in WSL by clicking the Status Bar button in the bottom-left corner of VSCode, underneath the gear icon. Then select Connect to WSL. By default it should open Ubuntu; if that doesn't work, click Connect to WSL using Distro and pick Ubuntu.

Note: Using WSL is optional but highly recommended for making your life easier when developing on a Windows machine.

3. (macOS) Install Homebrew

If you're on Windows or Linux, skip to 4.

Homebrew is the standard macOS package manager. It makes installing Git, databases, runtimes, and CLI tools a one-line command (brew install <thing>). Most tools in this guide — and most you'll reach for later — are easiest to install through Homebrew. Worth setting up once before anything else.

Install Homebrew

Open the Terminal app (press Command + Space, type "Terminal", hit Enter). Then paste and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You can verify this is the correct script at the official site: brew.sh.

Follow the prompts. At the end of the install, Homebrew will print two lines starting with eval (or similar) that add Homebrew to your shell's PATH. Copy and run each of those lines exactly as shown — otherwise the brew command won't be found in future terminal sessions.

Verify

Close and reopen your Terminal (so the PATH change takes effect), then run:

brew --version

You should see a version number. If you get "command not found", re-read the end of the Homebrew installer output and re-run the eval lines it printed.

If You Encounter Issues:

  • Paste the terminal output into an LLM (Claude, ChatGPT, or Gemini) and describe what went wrong.

4. Install uv for Python code

uv is an extremely fast Python package manager that simplifies creating and managing Python projects. uv makes working with Python both faster and simpler.

Install uv

In VSCode, at the top of the screen, select Terminal > New Terminal. Then copy and paste the command below. You can verify the script at the official uv site, maintained by Astral: Install uv.

curl -LsSf https://astral.sh/uv/install.sh | sh

If you are on Windows and not using WSL:

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

What This Command Does:

  • curl -LsSf: Downloads the install script silently (-s), follows any redirects (-L), shows errors if silent mode hides them (-S), and fails on HTTP errors (-f).
  • | sh: Pipes the downloaded script into your shell, which executes it — this is what actually installs uv.

If You Encounter Issues:

  • Copy and paste your terminal output into an LLM (Claude, ChatGPT, or Gemini) and describe what went wrong.

5. Test Your uv Installation

Open the Terminal in VSCode

  • Select Terminal > New Terminal from the top menu.

Run the command:

uv

Expected output:

If uv was installed correctly, you should see a help message that starts with something like:

An extremely fast Python package manager.

Usage: uv [OPTIONS] <COMMAND>

Commands:
  run      Run a command or script
  init     Create a new project
  ...
  help     Display documentation for a command

If you get an error:

  • Paste the exact error message into an LLM and explain you’re having problems using uv.

If uv displays its usage information without an error, congratulations — you're set for Python.

6. Install Bun for JS and TS code

Bun is an extremely fast runtime and package manager that simplifies creating and managing JavaScript (JS) or TypeScript (TS) projects. Bun makes working with JS and TS code both faster and simpler.

Install Bun

In VSCode, open a new terminal (Terminal > New Terminal). Paste the command below. You can verify the script at the official Bun docs: Bun Installation.

curl -fsSL https://bun.com/install | bash

If you are on Windows and not using WSL:

Windows PowerShell:

powershell -c "irm bun.sh/install.ps1|iex"

What This Command Does:

  • curl -fsSL: Downloads the install script silently (-s), follows any redirects (-L), shows errors if silent mode hides them (-S), and fails on HTTP errors (-f).
  • | bash: Pipes the downloaded script into bash, which executes it — this is what actually installs Bun.

If You Encounter Issues:

  • Paste your terminal output into an LLM (Claude, ChatGPT, or Gemini) and describe what went wrong.

7. Test Your Bun Installation

Open the Terminal in VSCode

  • Select Terminal > New Terminal.

Run the command:

bun

Expected output:

If Bun was installed correctly, you should see a help message starting with something like:

Bun is a fast JavaScript runtime, package manager, bundler, and test runner.

Usage: bun <command> [...flags] [...args]

Commands:
  run       ./my-script.ts       Execute a file with Bun
            lint                 Run a package.json script
  test                           Run unit tests with Bun
  x         prettier             Execute a package binary (CLI), installing if needed (bunx)
  repl                           Start a REPL session with Bun
  exec                           Run a shell script directly with Bun

  install                        Install dependencies for a package.json (bun i)

(Your version number and commit hash may differ — that's expected.)

If you get an error:

  • Paste the exact error message into an LLM and explain you’re having problems installing Bun.

8. Install Make for Make commands

Many projects ship a Makefile — a small file listing common commands (make install, make test, make run, etc.) that bundle several steps into one. Make is the tool that reads that file and runs those commands. It's been a standard part of Unix-style development for decades, and you'll encounter it in both Python and JavaScript/TypeScript repositories.

Install Make

  • macOS (with Homebrew from step 3): brew install make. Alternatively, xcode-select --install bundles Make along with Apple's Command Line Tools.
  • Windows (WSL): Make is usually pre-installed in Ubuntu on WSL. If not, install the full build toolchain (recommended — includes Make, gcc, and related tools): 
    sudo apt-get update && sudo apt-get install build-essential
    Or just Make on its own: sudo apt-get install make.
  • Windows (no WSL): The easiest route is to use WSL (step 2). If you'd rather install Make natively on Windows, use Chocolatey (choco install make) or Scoop (scoop install make).
  • Linux:
    • Ubuntu/Debian: sudo apt-get install build-essential (or sudo apt-get install make for just Make)
    • Fedora: sudo dnf install make

Verify Make installation

Open a new terminal and run:

make --version

You should see output starting with something like GNU Make 4.x. If you get "command not found", re-run the install command for your OS above.

Using Make

Once installed, navigate into any project folder that contains a Makefile and run:

make <target>

where <target> is one of the commands defined in that project's Makefile (e.g. make install, make test). Running make with no target usually runs the first target in the file, and make help often prints a list of available targets if the project defines one.

If You Encounter Issues:

  • Paste the terminal output into an LLM (Claude, ChatGPT, or Gemini) and describe what went wrong.

9. Install Git on Your Computer

Git is the version control system that lets you sync your local code with online repositories on GitHub.

Install Git

  • macOS (with Homebrew from step 3): brew install git. Alternatively, run xcode-select --install to get Apple's Command Line Tools — git comes bundled.
  • Windows (WSL): Git is usually pre-installed in Ubuntu on WSL. If not: sudo apt-get install git.
  • Windows (no WSL): Download the installer from git-scm.com and follow the prompts.
  • Linux:
    • Ubuntu/Debian: sudo apt-get install git
    • Fedora: sudo dnf install git

Verify Git installation

git --version

You should see the installed version number.

10. Create a Free GitHub Account

GitHub is a platform that hosts your code online and helps with version control and collaboration.

Sign up

  • Go to GitHub and create a free account if you don’t already have one.

Explore GitHub

  • Once you have an account, you can create repositories, explore others’ code, and collaborate on projects.

11. Sign In to GitHub with the GitHub CLI (recommended)

GitHub publishes an official command-line tool called gh that handles authentication in a single command. This is the recommended way to sign in — no SSH key generation, no personal access tokens to create and paste, no re-prompting for credentials on every push.

Install gh

  • macOS: brew install gh
  • WSL / Ubuntu / Debian: sudo apt install gh
    (If your package manager can't find it — on older Ubuntu versions — follow the install steps at the official docs.)
  • Fedora: sudo dnf install gh
  • Windows (no WSL): Download from cli.github.com.

Verify:

gh --version

Configure Git with your name and email

These show up on every commit you make, so set them once:

git config --global user.name "Your Name"
git config --global user.email "YourEmail@example.com"

Authenticate with GitHub

Run:

gh auth login

Walk through the prompts:

  1. GitHub.com (not GitHub Enterprise, unless your school or workplace uses one)
  2. HTTPS (easier than SSH for most people)
  3. When asked "Authenticate Git with your GitHub credentials?" → Yes
  4. Login with a web browser — gh will display a one-time code, open GitHub in your browser, ask you to paste the code, then confirm the authorization.

That’s it. You can now git clone, git push, and git pull on any GitHub repo without typing credentials — gh wires up Git's credential helper automatically.

Verify

gh auth status

You should see something like "Logged in to github.com account ".

Advanced: SSH method

If you prefer SSH keys (e.g. you're on a shared machine, or you want more granular per-device revocation):

  1. Generate a key:

    ssh-keygen -t ed25519 -C "your_email@example.com"

    Press Enter to accept defaults.

  2. Run gh auth login again and pick SSH instead of HTTPS when prompted. gh will offer to upload your public key to GitHub automatically — say yes.

For most people starting out, stick with HTTPS. You can always switch methods later with another gh auth login.

12. Install an AI Coding Assistant

An AI coding assistant will be the single biggest productivity multiplier in the setup you just built. If you're going to spend money on developer tooling in 2026, this is where it goes first. The baseline $20/month tier of either of the two options below is enough to meaningfully evaluate them — you don't need the top-tier plans to start.

Pick one of the two below. Both are excellent; the choice mostly comes down to which workflow you prefer. Try one for a month, and if it doesn't click, try the other.

Option A: Claude Code (Anthropic)

Claude Code is a terminal-native coding agent built by Anthropic. You run claude in any repo, and it reads your code, writes and edits files, runs shell commands, and iterates with you in plain English. There's also an integration for VSCode.

Install:

# macOS / Linux / WSL — via Homebrew (if available) or npm
brew install --cask claude-code
# or, cross-platform:
npm install -g @anthropic-ai/claude-code

Authenticate:

claude

Follow the prompts to log in with your Claude account.

Subscription: Claude Pro at $20/month is the entry tier. Claude Max ($100/mo or $200/mo) raises usage limits if you hit them. Sign up at claude.ai. Docs: docs.claude.com/claude-code.

Option B: Codex (OpenAI)

Codex is OpenAI's coding agent. Included as part of ChatGPT subscriptions and available as a CLI and IDE integration.

Subscription: ChatGPT Plus at $20/month is the entry tier. ChatGPT Pro ($200/mo) raises usage limits. Sign up at chatgpt.com.

Access: Use Codex inside the ChatGPT web app, or install the Codex CLI per the instructions at openai.com/codex.

Summary

Congratulations! You've installed and set up:

  • VSCode — simple and free code interface
  • WSL — if you're on Windows, an easier Linux-based dev environment
  • Homebrew — if you're on macOS, one-line install of almost any CLI tool
  • uv — Python project and package management
  • Bun — JavaScript and TypeScript runtime and package manager
  • Make — runs make <target> commands defined in a project's Makefile
  • Git + GitHub via gh CLI — version control and collaboration, authenticated in one command
  • Claude Code or Codex — your AI coding assistant

You're now ready to start coding with a solid local development environment. If you run into any issues, copy the error message into your AI assistant and describe what you were trying to do.