timestamp: 2026-06-20
tags: [naming, repo, npm, subdomain, family, branding]
Family-wide naming policy — repo, npm, subdomain
GitHub slug = npm name. Subdomains shorter. Suffix every repo
Naming policy across the family
The three name spaces
| Layer | Convention | Example |
|---|---|---|
| GitHub repo slug | <role-name>-<suffix> (lowercase, kebab-case) | chirag127/pdf-tools-site |
| npm package name | @chirag127/<same-as-repo-slug> (when published) | @chirag127/firebase-init |
| Subdomain | Shortest single word possible | pdf.oriz.in |
Rule of identity (when both exist): GitHub repo slug == npm package
name (modulo the @chirag127/ scope). No divergence. If the package
needs a different display name, that goes in package.json#name for the
import path (which equals the repo slug) and package.json#publishConfig
or README for the prose.
Rule of brevity for subdomains: Subdomains are typed by users every
day. Optimize for typing speed. pdf.oriz.in not pdf-tools.oriz.in.
The role-suffix matrix (hybrid)
Sites and npm packages drop the suffix; everything else keeps it.
| Category | Suffix | Example |
|---|---|---|
| Static site | (none) | pages, lore, tabs |
| Astro / JS / TS npm package | (none) | astro-shell, firebase-init |
| Browser extension | -ext | kagi-summarizer-ext |
| VS Code extension | -vsc-ext | snippets-vsc-ext |
| CLI tool | -cli | deploy-cli |
| Cloudflare Worker | -worker | api-worker |
| Cloudflare Function | -fn | og-image-fn |
| Model Context Protocol server | -mcp | knowledge-mcp |
| Static data repo | -data | redirects-data |
Sites + scoped npm packages drop the suffix because:
- Subdomain + homepage URL already mark a repo as a site.
- The
@chirag127/scope already disambiguates packages from public unscoped names.
Other categories keep the suffix because the brand alone doesn’t tell you the runtime, and the suffix is the cheapest possible way to communicate it.
What goes in the suffix vs. inside the slug
The suffix names the runtime category — what kind of thing this is, where it deploys. The slug body names the function — what it does.
- Bad:
chirag127/pdf-tools(no suffix; what kind of thing is it?) - Bad:
chirag127/site-pdf-tools(suffix as prefix; sorts wrong in repo listings) - Good:
chirag127/pdf-tools-site(function then category)
Brand prefix posture
- New repos: no
oriz-prefix in the slug. The org slugchirag127/is already the prefix.chirag127/pdf-tools-siteis redundant. - Legacy repos:
oriz-*survives until next deliberate rename. Don’t rename just for cosmetics. - Exception: when the slug body is a generic English word that would
collide with public packages or be ambiguous on its own, prefix with
oriz-for disambiguation. E.g.oriz-snippets-vsc-ext(becausesnippets-vsc-extwould shadow other VS Code extensions).
Cross-platform identity
The same project may exist as a repo, an npm package, a subdomain, and a binary. Names align like this:
| Project | Repo | npm | Subdomain | Binary |
|---|---|---|---|---|
| PDF tools site | pdf-tools-site | (not published) | pdf.oriz.in | (none) |
| Astro shell pkg | astro-shell | @chirag127/astro-shell | (none) | (none) |
| Deploy CLI | oriz-deploy-cli | @chirag127/oriz-deploy-cli | (none) | oriz-deploy |
| Knowledge MCP | oriz-knowledge-mcp | @chirag127/oriz-knowledge-mcp | (none) | (stdio) |
The CLI binary name CAN be shorter than the package — oriz-deploy
binary from @chirag127/oriz-deploy-cli is fine, since the binary is
typed daily but the package is referenced rarely.
(Decided 2026-06-20.)