Elixir Companies is a content repo, not an application

The data is markdown in src/content/companies, so editing it is a pull request

The unit of content here is one file per company. Adding a listing starts with a fork and a new file in `src/content/companies/` named `your-company.md`. That file is the entire record, frontmatter plus one paragraph describing the company and how it uses Elixir.

The frontmatter schema is the API. Required keys are `name`, `website`, `github`, `industry` and `location`, where location is a nested object of `city`, `state` and `country`, plus `lastChangedOn` as a date. Two optional keys exist and they are not decorative: `blog` points at a company blog URL, and `jobs` points at a careers page, which is what makes the listing show a Hiring badge.

So a complete entry looks like this:

---
name: "Your Company"
website: "https://example.com"
github: "https://github.com/your-org"
industry: "Information Technology"
location:
  city: "City"
  state: "State"
  country: "Country"
lastChangedOn: 2024-01-01
---

A description of your company and how you use Elixir.

The third step is a pull request. There is no admin tooling, no submission form, no API. For a public directory that is the right amount of process, and for a private fork it means your hiring team keeps the data current by merging one file at a time.

Industry values come from GICS, and the list is exactly fourteen entries

The `industry` field is not free text. The README states the available industries are based on the Global Industry Classification Standard, and it enumerates them: Communication Services, Consumer Discretionary, Consumer Staples, Education, Energy, Financials, Health Care, Industrials, Information Technology, Materials, Real Estate, Transportation and Utilities.

Fourteen values covering the whole economy is a deliberate simplification. A payments company and a hospital software vendor both land on Financials or Health Care respectively, and there is no room for a cross classification. If you fork the project for internal use, this is the field most likely to need extending, and the natural place to extend it is the frontmatter validation in your own site config rather than the file content.

The `location` object is equally rigid and equally awkward for a distributed company. There is no country only form. A company with engineers in several cities has to pick one, which means either the listed location is the headquarters or it is whichever office the submitter typed in.

`lastChangedOn` is the one field that carries editorial meaning. It records when the record was last touched, which is what lets a reader judge whether a claim about someone's Elixir usage is current. Nothing in the README says the project prunes entries whose `lastChangedOn` is old, so treat it as metadata a human is expected to read, not a mechanism that expires anything.

Astro 6 with Preact islands and Tailwind 3, deployed to GitHub Pages

The site is built with Astro and deployed to GitHub Pages, which is why the repository carries `astro.config.mjs`, `tailwind.config.mjs`, `postcss.config.mjs` and a `public/` directory rather than a server.

`package.json` names the package `elixir-companies`, marks it as an ES module, and carries three runtime dependencies: `astro` at ^6.3.5, `preact` at ^10.29.2 and `@astrojs/preact` at ^5.1.3. Styling is Tailwind ^3.4.0 with autoprefixer ^10.4.0 and @tailwindcss/typography ^0.5.0 in devDependencies. Preact is there because a directory site wants small interactive islands, and the Preact integration is how Astro renders them.

The npm scripts are small enough to read in one glance:

"scripts": {
  "dev": "astro dev",
  "start": "astro dev",
  "build": "astro build",
  "preview": "astro preview",
  "convert": "node scripts/convert-exs-to-md.mjs"
}

That last script is worth noting. `convert` runs a repository script that converts exs files to markdown, which is the remnant of how content was stored before the move to the markdown frontmatter format that `src/content/` uses today. If you are migrating an old fork, that script is where the old shape of the data lives.

There is a version mismatch worth flagging. `package.json` says version 3.0.0 while the latest tagged release is v1.1.0 from 2025-08-25, preceded by v1.0.0 from 2025-04-22. The site itself pushes regularly, with the last push on 2026-10-08, so the Git tags and the package version are simply not kept in step.

Running the site locally: Node 20 and two commands

Development needs Node.js 20 or newer, per the README prerequisites. Setup is two commands:

npm install
npm run dev

The dev server starts and the README points you at localhost:4321, which is Astro's default port. Because the port is named in the README, a conflict with another Astro project on the same machine is the first thing you will hit.

For a production check before pushing:

npm run build
npm run preview

`npm run build` is `astro build` and `npm run preview` is `astro preview`. The value of running preview after build rather than only dev is that content collection validation errors surface at build time, and that is the moment a malformed frontmatter key or an industry value outside the documented set becomes visible.

A repository level `package-lock.json` is present, so `npm install` is reproducible for a given commit. There is no CI configuration listed beyond a `.github/` directory, and the README does not describe what it runs.

What a curated list cannot tell you, and what it can

The honest scope of this project is a claim that a named company uses Elixir in production. That is a real signal for a job seeker or for someone deciding whether an ecosystem has commercial weight, and the README's positioning as a curated directory is not overclaiming.

What it is not is a survey. There is no methodology section, no survey date, no definition of what qualifies as production use, and no editorial policy described for who reviews submissions. Entries come in through pull requests. That means coverage is a function of who noticed the company and filed the pull request, not of a systematic sweep.

The `jobs` field and the Hiring badge show the intended secondary use: pointing at a careers page. That makes the directory partly a job board index, which the repository topics confirm by listing `joblist` and `jobs` among its topics alongside `phoenix` and `elixir-programming-language`.

Because the primary language of the repository is listed as Astro and the content is markdown, the site itself has no Elixir in it at all. Do not read the repository as an Elixir project. It is a content pipeline with a static site in front of it.

Fork it, self host it, or just read the raw markdown

The alternatives are not really alternatives in the software sense, which is worth saying before anyone compares them.

If you want the data and nothing else, read the markdown directly. Every record in `src/content/companies/` is a text file with frontmatter, so a script that wants the industry or location of each company needs nothing from Astro at all. The site build is a convenience for reading it in a browser.

If you want a directory on your own domain with your own listings, the fork is the path. The MIT licence in the LICENSE file at the repository root means you can take the source, drop the existing entries, and keep the Astro setup. You inherit the frontmatter schema, the GICS industry list and the Tailwind styling, and you accept responsibility for all three.

If you want the maintained public list, use the site at elixir-companies.com rather than deploying your own copy. Forking means you are now responsible for the freshness of a list whose only currency signal is `lastChangedOn`, and no automation in the repository will tell you when an entry has gone stale.

Editorial conclusion

Fork elixir-companies if you want a private directory of Elixir shops for recruiting or for tracking an ecosystem, because the content model is three lines of frontmatter and one body paragraph you can generate yourself. Do not expect a maintained list: the site describes itself as curated, the README documents no review policy or listing expiry, and a stale entry stays up until someone edits it. Verify first that your own `src/content/companies/` files pass the frontmatter the README specifies, including `lastChangedOn` and one of the documented GICS-based industry values, since the build reads those keys rather than anything you improvise.

Frequently asked questions

Official sources

1. beam-community/elixir-companies on GitHub
2. License: MIT
3. Project website
4. README
5. Releases