A useful development setup is the smallest one that lets you edit, run, and safely change your project. You do not need to install every language runtime, framework, editor extension, and command-line tool before writing your first page.
This guide sets up a practical baseline for web projects on Windows, macOS, or Linux. A static HTML and CSS site needs less than a JavaScript app with a build tool, so add tools only when your project calls for them.
Choose the tools your project needs
| Project | Start with | Add when needed |
|---|---|---|
| A static HTML, CSS, and JavaScript site | A text editor, a modern browser, and Git | A local server or build tool if the project needs one |
| A JavaScript app or site with build scripts | A text editor, a browser, Git, and the Node.js version required by the project | The package manager and framework named in the project documentation |
| An existing repository | The tools and versions listed in its README and configuration files | Nothing that conflicts with its documented setup |
MDN's web development environment setup guide also starts with a text editor and modern browsers. If you are following an existing project, its setup instructions take priority over a generic checklist.
1. Install an editor, Git, and Node.js when required
Choose an editor you are comfortable using. Visual Studio Code's getting-started guide is one place to begin; the specific editor matters less than being able to open a project folder, edit files, and use a terminal.
Install Git using the instructions for your operating system in the Pro Git installation guide. On macOS and Linux, Git may also be available through the operating system's developer tools or package manager. Use the instructions for your own system rather than copying commands from another platform.
Install Node.js only if your project needs it, such as for a JavaScript build tool, package scripts, or a Node.js server. Check the repository's README, package.json, and any version file first. For a new project without a version requirement, choose a supported LTS release from the Node.js release schedule, rather than assuming the newest Current release is the right fit.
2. Check that the terminal can find the tools
Open a new terminal after installing tools, then check the commands you need:
git --version
node --version
npm --version
The last two commands apply only when Node.js is part of your project setup. If a command is not found, confirm that the tool is installed, open a fresh terminal, and check that its install location is available through your system's PATH. On Windows, where.exe node can show which Node executable the terminal finds; on macOS and Linux, use command -v node.
If the version differs from the one in the project instructions, resolve that before installing dependencies. Multiple projects can require different runtime versions, so do not overwrite a working project setup just to use the newest release.
3. Start a project without adding unnecessary dependencies
For an existing project, follow its README and use the package manager and commands it documents. For a small new JavaScript project, you can create a folder and initialize its package metadata with npm:
mkdir weekend-site
cd weekend-site
git init
npm init -y
The npm init command creates a package.json for the project. If a framework's official starter command is the right starting point, use that instead of running a second scaffold on top of it. For a static page with no build step, you can skip Node.js and npm init entirely.
To check that Node.js can execute a short script, run:
node -e "console.log('Node.js is ready')"
This only checks that Node.js runs; it does not install project dependencies or verify that an application works. Run the project's own development, test, and build commands when they are available.
Configure the name and email Git will use for commits by editing your global Git configuration:
git config --global --edit
Set the [user] name and email values in that file. If you want different commit details for just this repository, run git config --local --edit from its directory instead. GitHub's Git setup guide explains this configuration. For the next steps after setup, see our guide to practical Git and GitHub workflows for small projects.
4. Keep generated files and secrets out of Git
For a Node.js web app, a starting .gitignore might look like this:
node_modules/
dist/
.env
.env.*
!.env.example
Adjust it for the output folders your project actually creates. The .env.example exception keeps a sample configuration file trackable after the .env.* rule; include variable names and safe example values there, never working credentials. GitHub explains how ignore rules work.
Do not treat a .env file as a guarantee that a value is secret. Front-end build tools can copy selected variables into browser-delivered code. For example, Vite's environment-variable documentation explains that variables with its VITE_ prefix are exposed to client-side code. Keep private API keys and other server credentials on the server, outside anything shipped to a browser.
When you add dependencies, use the package manager chosen by the project and commit its lockfile for an application. npm's package-lock documentation describes how package-lock.json records the dependency tree. Avoid committing node_modules or creating a second lockfile with a different package manager.
Troubleshoot the common setup failures
- A command is not found: Install the tool for your operating system, open a fresh terminal, and check
PATHbefore reinstalling it. - The project reports an unsupported runtime: Re-read its documented Node.js version and use that version; do not change the project configuration just to silence the error.
- A teammate gets different dependency versions: Check that everyone is using the same package manager and that the application's lockfile is committed.
- A secret appears in a browser bundle or Git diff: Remove it from the client-side code or repository, rotate the credential, and check the ignore rules. An ignore rule does not remove a file that Git already tracks.
Start with the smallest setup that runs your project. Add tools when a project requirement calls for them, keep its runtime and dependency choices documented, and use Git to make changes reviewable and reversible.