remote-jobs: the production build deletes two directories under src

Every production build wipes two directories that live under src

The build script is a chain, and its first link is a clean.

    "clean": "rimraf dist src/_includes/css src/_includes/scripts",
    "clean:og": "rimraf src/assets/og-images",
    "start": "npm run dev:11ty",
    "build": "npm run clean && npm run build:11ty && npm run pagefind"

Read what `clean` targets. Two of its three paths are not build output. `dist` is, but `src/_includes/css` and `src/_includes/scripts` sit inside the source tree, and the build deletes them unconditionally before every run. That tells you those two directories are generated rather than authored, and it means anything you put in them by hand is gone the next time you build, with no warning beyond the rimraf. The other detail worth catching is that the generated assets are cleaned by two separate scripts, since `clean:og` handles the Open Graph images on its own. So "clean the project" is not one operation here, and running only the first one leaves a third category of generated files sitting in the tree.

The dev server and the build are not the same pipeline

The README gives three commands and the middle one is not the build.

npm install         # Install dependencies
npm run start       # Dev server with hot reload
npm run build       # Production build

`npm run start` resolves to the development server, which sets the Eleventy environment to development and serves. It does not clean, and it does not build the search index. The `pagefind` step only appears inside the full build, and it is the last link in the chain, which means a failure there leaves you with a complete site in `dist` and no index, which is easy to mistake for a working build if you only check that pages exist. Note also that this step shells out to `npx pagefind` rather than to a binary from `node_modules`, scanning the built HTML in `dist`, so that one stage resolves its own tool at execution time instead of taking it from the lockfile. The practical rule for contributors is to treat the dev server as a preview of layout and the full build as the only thing that tells you whether the site is actually shippable.

Four transitive versions are held still by an overrides block

The manifest carries an `overrides` section that pins four packages the project does not depend on directly.

  "overrides": {
    "nanoid": "^5.0.9",
    "liquidjs": "^10.27.2",
    "ws": "^8.21.0",
    "sharp": "^0.35.3"
  },

These are transitive dependencies, and the overrides say that whatever version an upstream package asks for, this project gets these. It is a normal way to keep a build stable, and it also creates a specific class of confusion. If you add a dependency that itself pulls one of these four, you do not get the version that dependency requested, you get the override, and the mismatch will not be visible in that dependency's own metadata. Sharp and nanoid are both native or binary-adjacent packages where the installed build matters, so when the build behaves differently on your machine than on the deployed site, this block is one of the first things to compare. Note also that `keywords` in the manifest is an empty array, which tells you the package is not published for discovery.

The listing rules are enforced by a bot that comments, not by the build

Adding a company is described in five steps, and the fourth is the one with teeth.

Create `src/companies/{slug}.md`, fill in the frontmatter, run `npm run build`, and open a PR. The bot will comment with any issues to fix. Note what the build does and does not check. It renders the site, so a file with malformed frontmatter fails loudly and locally. It does not know the field values the project accepts, because those live in `CONTRIBUTING.md`, which the README points to for the frontmatter template, the valid field values, the required sections, and what the validation bot inspects. So you can get a clean local build and still have the pull request sent back. The bot comments rather than rejecting, which is friendlier and also means a pull request can sit open with unresolved field values while the conversation continues. Read `CONTRIBUTING.md` before writing the file, not after the bot tells you what was wrong with it.

A company is one markdown file, and the slug is its identity

The data model is a directory of files, `src/companies/`, with one file per entry named by slug. That choice has consequences worth weighing. Adding a company is a create, correcting one is an edit, and removing one is a delete, so the full history of the directory is legible in version control, including the dates when a company's listing was last touched. What that history cannot tell you is why an entry says what it says, because the README does not say what the frontmatter records. Whether a company entry carries a verification date, a source link, or a named reviewer is a question for `CONTRIBUTING.md` and not for the README, and the difference matters for a directory whose whole value is that its entries are accurate. Treat the files as claims with an unknown level of backing until you have read the contribution guide and looked at what other entries actually contain.

The project's two descriptions disagree about whether semi-remote counts

Compare the two sentences that define the project. The README calls it a community-maintained directory of remote-friendly tech companies. The manifest description calls it a list of semi to fully remote-friendly companies in or around tech. Those are different scopes. The first implies companies that are remote, the second explicitly admits companies that are only partly so, and the phrase in or around tech widens the field past tech companies proper into companies adjacent to the industry. The consequence is that the boundary of the directory is not settled anywhere in the project's own text, so whether a given company belongs is a judgment the maintainers make on each pull request rather than a rule you can check before spending time on one. If you are adding a company that is hybrid, or one that is not a tech company, expect the answer to depend on who reviews it, and expect to be asked for justification you cannot point at documentation for.

Node 22 is stated clearly, and the environment file is not explained at all

The version requirement is unambiguous. The README says it requires Node.js 22+, the manifest sets `engines` to `>=22`, and there is a `.nvmrc` at the root so the intended version is recorded in a form your editor and version manager will pick up. Then there is `.env-sample`, also at the root, and `dotenv` in the development dependencies, which together mean that some part of the build or the dev server reads configuration from environment variables. The README does not name a single one of those variables, and none of the three development commands reference them explicitly. So if your local run behaves differently from the deployed site, the sample file is the first place to look, because it is the only place in the repository that says what the build expects to find. The gap is small and easy to close, but it is not closed for you, and it is the kind of thing that turns into a long debugging session when a key is simply missing.

Editorial conclusion

Use it if you want to add or correct a company in a directory that other people also maintain, and you are comfortable with a static site build and a pull request review loop. Do not use it as a job board, because it lists companies rather than openings, and do not treat its own README as the specification, since the frontmatter template and the valid field values live in a separate file. Before you open a pull request, read CONTRIBUTING.md end to end, run the build once so the bot has something to check, and look at the .env-sample before you assume a local build failure is your machine.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository