remy/mit-license: a permalink for your MIT license, and when that is a bad idea

What remy/mit-license solves, and for whom

The README opens with the author's own reason for building it: he forgets to add a LICENSE file to his projects, so he wanted a single resource that would stay up to date and always carry his details. The result is a hosted page per name. Linking https://rem.mit-license.org resolves the CNAME rem against the copyright holder stored in the users directory, so the MIT license text is rendered with the right name and the current year. The audience is therefore people who want to point at a license without committing a file: a personal site, a talk, a snippet, a side project that never got a repository. It is not a tool for generating the LICENSE file inside a repository you publish, and it is not a license chooser. The MIT text is the content; the project only fills in the holder fields.

The user.json file is the whole data model

Each host on mit-license.org is one JSON file in the users directory, named after the CNAME. The README states the minimum requirement is a copyright field and that everything else is optional, and it warns to keep the file valid JSON. The optional fields are url, email, format, gravatar, theme and license. The copyright value can be a plain string, an array of strings (rendered with "and" between the names), or an array of objects carrying name, url and email per holder. The url field turns the copyright text into a link, and email is displayed after the copyright notice with mailto: added automatically. Two constraints are easy to miss. The gravatar boolean requires the email property, and the README adds that you also need to check the compatibility of the chosen theme. The format field accepts txt and html only, and the date always shows the current year, so the page is not a frozen snapshot.

Creating a page through the API

The README documents three routes to your own page: the generator at richienb.github.io/mit-license-generator, a request to the API, or a fork and pull request. The API accepts a POST whose body is JSON, and the README shows three equivalent encodings: a JSON string, an explicit application/json content type, and URL query parameters. The example below is the minimal call, taken from the README, where rem is the subdomain you are claiming. If the user is not already taken, the README states the new user file is created on the fly and the URL is immediately available. There is no authentication in the documented flow, which is worth pausing on before you point anything important at it.

curl -d'{ "copyright": "Remy Sharp" }' https://rem.mit-license.org

Installing the server and rendering your first page

The repository is an Express application. package.json declares "start": "node .", "dev": "nodemon ." and "test": "xo && node test.js", pins the runtime to Node 24.x, and marks the package private with version 2.0.0. A Procfile sits at the top level for process-based deployment, and the server entry point is server.js. The commands below are the ones the package manifest defines; the README does not document a local install walkthrough, so treat this as reading the manifest rather than a documented procedure. After starting, a request to the host for a user that exists in the users directory renders that user's license page, and a request for a name that does not exist is what the API creation path is for.

npm install
npm start

Themes are CSS files, and that is the extension point

A theme is a CSS file added to the themes directory, and the README notes that you can use the latest CSS technologies because they are automatically polyfilled. The dependency list backs that up: postcss-middleware and postcss-preset-env are in the runtime dependencies, not the dev dependencies, so the polyfill runs as part of serving, not as a build step. To select a theme you add the theme property to user.json. The README lists a set of contributed themes including default, flesch, eula-modern, afterdark, orange, plaintext, double-windsor, cherry, white cherry, blackwood, hipster-gray, xtansia, magic-mint and default-dark. The catch is the one already noted: gravatar and theme interact, and the README tells you to check compatibility rather than promising it. A theme that does not lay out an avatar will not gain one from the gravatar flag.

Where it is the wrong tool

The hosted page is not a substitute for the LICENSE file in a repository. GitHub detects license files by filename and content in the repository itself; a link to mit-license.org does not do that, and nothing in the README claims otherwise. The second limitation is update friction. If you create a page through the API with only a copyright field and later want to add url, email, gravatar or a theme, the README is explicit: you need to send a pull request on that user.json file via GitHub. So the easy path in is not the easy path to edit. The third is the subdomain as a shared namespace. The name you want may already be claimed, and the README's own fallback when automated creation fails is to send a pull request. There is also no release history in the repository, so pinning to a version is guesswork beyond the 2.0.0 in package.json.

Alternatives and the actual difference

The obvious alternative is the generator the README itself recommends as the easiest route, richienb.github.io/mit-license-generator. The difference is where the state lives. The generator produces a page or text once, for you to copy; remy/mit-license keeps the record in this repository and serves it at a stable subdomain, which is the entire point of the permalink idea and also the source of the update friction. A second alternative is committing a LICENSE file directly to each project. That gives you version control, review and a copy that travels with the source archive, at the cost of remembering to do it in every repository, which is the exact problem the README describes in its first line. A third is forking this project and sending a pull request, which the README offers as a first-class path rather than a workaround, and which makes sense when you want changes to the theme or the server rather than just a page.

Licence, maintenance and upgrade cost

package.json declares the project's own license as MIT, while the repository metadata reports NOASSERTION, so the manifest and the platform agree only in one direction; if you fork, read the LICENSE file at the top level rather than the metadata line. That distinction matters because the whole product is a copy of the MIT license text, and you are redistributing it. On maintenance, the last push to the default branch master was on 2026-07-06, which is within six months of this writing, so the repository is not dormant by that measure. The runtime is pinned to Node 24.x, and the dependency list is long for what the app does: Express, EJS, Octokit, postcss-middleware, gravatar-url, create-html-element and others. Upgrading means moving that set together, and the test script runs xo plus node test.js, so linting is part of the gate. There are no releases in the repository, which means no changelog to read before an upgrade.

Editorial conclusion

Adopt it when you want a stable URL that shows the MIT license text with your copyright line and nothing else, for example in a slide deck, a README badge or a talk. Do not adopt it as the LICENSE file of a repository you publish: the repository needs its own LICENSE file, and the README recommends the generator for one-off pages rather than running the server. Before relying on a subdomain, check that the name you want is not already taken in the users directory and that your user.json parses, since the README states the minimum requirement is a copyright field and that the file must be valid JSON.

Frequently asked questions

Official sources

1. Issues
2. README
3. remy/mit-license on GitHub