Project layout and scripts

There is no standard enforced by anything, and yet open twenty JavaScript projects and you will see the same shape nineteen times. Knowing the shape is the difference between opening an unfamiliar repository and knowing where to look, and opening it and closing it again.

The root holds the project's identity and configuration: package.json, the lockfile, a README, a .gitignore, and a small pile of tool configuration files. Your code lives in src. Tests live in tests, or beside the file they test. Anything a build produces goes in dist or build. Anything served as-is - images, fonts, an icon - goes in public or static.

The one folder that is not like the others is node_modules. It is not yours, it was not written by anyone on the project, and it is reproducible from two small files. Every other folder in the list is authored; that one is downloaded.

Split everything you see into authored and generated, and half the confusion goes away. Authored files are the ones a person edited on purpose: src, tests, the README, package.json, the config files. Generated files are produced by a command: node_modules, dist, coverage reports, build caches.

Two rules follow, and they are worth having as reflexes. Never edit a generated file - your change will be overwritten by the next build, and it will not exist for anybody else. Never commit a generated folder - it is large, machine-specific and reproducible, and .gitignore exists to keep it out.

The lockfile is the one that looks generated and is committed anyway, which is why it confuses people. It IS generated - by npm, not by you, and you never hand-edit it - but it is committed because it is the record of exactly which versions were installed, which is the whole point of the previous lesson.

The scripts object in package.json is a named list of the commands this project supports. npm run build runs whatever build is defined as; npm run dev starts the development server; npm test runs the tests. Two names are special enough to have their own commands: npm test and npm start work without the word run.

This is more valuable than it first looks, for a reason that has nothing to do with saving keystrokes. A script is documentation that cannot go stale, because it is also the thing people actually run. If the test command changes, it changes here, and everybody picks it up on their next pull. A README that says "run mocha --recursive" is a claim about the past; "npm test" is a claim the project keeps true.

There is a second reason, and it is the one that ends "works on my machine" arguments. npm run puts the project's own node_modules/.bin at the front of the PATH, so a script that says vitest run uses the version this project installed and pinned - not whatever version happens to be installed globally on your laptop. The script and the lockfile together are what make one command mean the same thing on two machines.

Do it in the same order every time and it takes five minutes rather than an afternoon. First, package.json - and inside it, scripts before anything else. That tells you how to run, test and build the thing, which is most of what you need to be useful. Then the dependency lists, which tell you what kind of project this is: a framework in there tells you more than the folder names will.

Second, the README. Not for the API details, which are usually stale, but for the project's purpose and any setup step the scripts cannot capture, like a required environment variable.

Third, the entry point. main or exports in package.json names it, or the dev script does; open that file and read its imports. The first fifteen lines of an entry file are a map of the whole system, because everything the program uses has to get in through there.

Fourth, and only now, the folders. By this point you are not browsing at random - you are looking for something specific, which is the difference between exploring and being lost. And if the project has tests, read one: a test is a worked example of the code being used correctly, written by someone who had to make it actually run.

Running a tool globally instead of through a script. npx some-tool or a globally installed binary can be a different version from the one the project pinned, and the failure it produces will not reproduce for anybody else. If a project has a script for it, use the script.

Editing files in dist or build. They are output. The next build overwrites them, and the source they came from is still wrong. Find the file in src that produced it.

Treating the absence of a folder as a mistake. Not every project has src, not every project has tests, and plenty of good ones colocate tests beside the code they cover. The shape is a convention with useful variations, not a rule anybody has to follow.

Assuming a config file at the root is boilerplate to ignore. Those small files are where a project's real behaviour is decided - which files the type checker sees, what the linter forbids, where the build output goes. When something behaves in a way the code does not explain, the explanation is usually in one of them.

A typical project keeps configuration and identity at the root, source in src, tests in tests or beside the code, build output in dist, static assets in public, and dependencies in the one folder nobody authored. Sort everything into authored and generated: never edit or commit the generated, with the lockfile as the deliberate exception. The scripts block is the project's front door and its most reliable documentation, and it runs the project's own pinned tools rather than whatever is on your machine. To orient yourself: scripts, then README, then the entry file, then the folders - in that order.