Introduction

You are getting ready for your next assignment. Should be an easy job, just update some templates to implement a new menu design, so let's get down to it. Clone this git repo, allright! Wait...wut... what is all this stuff?

My assumption is that a lot of developers have gone through such a moment, where you look a new project in the face and think: what is all this stuff? To help you get back down in your seat again and approach this with some confidence, I will drill down some more common frontend setups that you will encounter anno 2020.

Note: this is (of course) not a full, exhaustive list. Every project is different, and I've seen some rare custom setups over time. This article is aimed to help starting developers to find their way in most projects.

Anatomy of frontend repositories

Files

Independent of framework or type of project, there's going to be a bunch of files in the root folder.

• README.md (make a readme)
  Always start here. A lot of tools by default open a README file if they find it in the root. Most of the time, this is the best place to find documentation written by the actual maintainers of this project about how to get started, requirements to be able to run it, and possible other details that are relevant.

• LICENSE (license help)
  Some legal information about usage, warranty and sharing of the code. Also often refer to standard software licenses like MIT, GNU, etc.

• package.json (npm docs)
  This is also important to peek into. A package.json file indicates that this project relies on the npm ecosystem. Wether or not this project is actually exposed publicly, beside details like name/description/author of this project, it usually also lists dependencies (other packages from npm). Another important aspect is that it often lists a couple of npm scripts that perform certain tasks within a project, like installing dependencies, start a development environment, test the codebase and build/bundle for production. For node projects, the main field in the package.json is rather important as it targets it as the entry point for the package. For website packages, this is not relevant.

• package-lock.json (npm docs)
  The package lockfile holds metadata about which dependencies were installed in the node_modules. This is very useful to be able to exactly reproduce a specific situation, as by design dependencies are able to be of different version depending on when you run your install command (by allowing patch and minor updates, see semver).

• .gitignore (git on gitignore)
  This file has instructions of what to exclude from version control. It can be specific files, as well as entire directories. Think about the build-output of your project, temporary folders or dependencies. Common items include node_modules, tmp, dist, www,build and so on.

• .editorconfig (editorconfig docs)
  To avoid unneeded clashes of handling charactersets and whitespace, this file will help editors pick (among others) tabs vs spaces, level of indentation and how to handle newlines, based on filename/extension.

• .[SOMETHING]rc
  What exactly is the definition of RC is not entirely clear , but all those RC files are basically configurations for anything that runs in your project and supports it. Often you will find these: .npmrc, .babelrc, etc.

• [SOMETHING].config.js [SOMETHING].config.json
  Configuration settings for the specified...thing. Think of linters (eslint, prettier), transpilers (babel,traceur), bundlers (rollup,parcel,webpack), typescript (ts), etc.

Folders

• node_modules (npm on folders)
  All installed dependencies will go in here. Usually this folder is created once you run npm install or yarn install, as it almost always is ignored by git (see .gitignore).

• scripts (undocumented convention)
  Command line actions from the package.json often refer to executing files in this folder. Building, linting, testing, often the instructions for performing these tasks are in here.

• src (undocumented convention)
  The real meat: the source code of this project. Probably 90% or more of the repo activity has its place in this folder.

• assets (undocumented convention)
  Any audio, image, font, video or other static assets are often stored together here.

• build|dist (undocumented convention, Stack Overflow question)
  The bundled or optimized output of the sourcecode. Depending on the goal of this repo, this may or may not be included in git, so you might have to run some build script first before this will be summoned into existence.

• tmp | .tmp (undocumented convention)
  When running projects in development mode, it often needs temporary workspace to serve to the browser, it might need intermediate files. Either way, this folder is as it states, temporary. Don't expect it to be there for long.

• bin (convention, probably originates in linux and other operating systems)
  Any command-line executables are defined here. In the scope of frontend projects, it is mostly limited to some command-line utilities like scaffolding tools (for example generate new pages or components).

• lib | vendor (undocumented convention)
  Sometimes you need libraries that you cannot, or do not want to rely on through npm. 3th party assets are often stored in this folder.

• test (undocumented convention)
  For tests that you don't want next to your source code, there is a separate directory. Direct page testing is often something that is written in this folder.

Enjoy your journey

This is just scratching the surface, hopefully this gives beginning developers a clue on what to expect when starting with projects. Basically my advice usually is:

• Start with the README! Other maintainers want you to read this first before getting your hands dirty;
• Next up: package.json: see what script instructions there are for installation, development, testing and building.
• Lets get to it! src: look at how this folder is organised, probably you will start recognising things here and get a clou of how to get things done.

I know that those instructions sound almost blatantly straightforward, but how often did I have someone at my desk asking how to get a project up and running, where I would reply... Did you read the README?

Some follow-up for this could be a repository which holds a lot of those files with comments and readme's, that can be a community-driven effort to explain what it all does in a nice, kind-of interactive way. Let me know in the comments if you would like to see such an initiative!