Naming projects well from the beginning can prevent lots of labor to correct down-the-line. Many projects grow to accomodate new requirements over time, so while we can't predict the future and always prevent refactoring names, we can still try to measure twice, name once.
Passing a project name through kebabCase() should ideally always return the repository name. And the README.md, composer.json and package.json names should generally sync up (with the exception of the @ organization prefix in JavaScript).
In lieu of fancy codenames and clever, aspirational abstracts, we largely follow the following convention:
We have prescribed prefixes for many of our Common Product Conventions below.
Please keep reading to understand when platform and type conditionally apply.
The platform is the destination technology where the code executes. These may be a specific service, library or more general language identifier.
| Tag | Platform |
|---|---|
aws |
Amazon |
cf |
Cloudflare |
gatsby |
Gatsby |
gh |
GitHub |
laravel |
Laravel |
wp |
WordPress |
wp-cli |
WP-CLI |
node |
Node |
webpack |
webpack |
php |
php |
js |
js |
react |
React |
The type often reflects a specific classification or product name that comes from a library or service.
aws-lambda-{name}cf-worker-{name}gatsby-plugin-{name}gatsby-theme-{name}gh-action-{name}wp-plugin-{name}wp-theme-{name}
This list is not comprehensive, please see the Common Product Conventions below.
The name should aim to be brief, descriptive and inclusive of potential growth, without getting verbose, jargon-y or overly specific.
| Avoid | Preferred |
|---|---|
aws-lambda-headless-png-screenshot-service |
aws-lambda-screenshot-service |
wp-module-frontend-filebased-caching |
wp-module-performance |
wp-plugin-bluehost-support-desk-integration |
wp-module-support (then added to wp-plugin-bluehost) |
gh-action-lint-build-wp-plugin |
gh-action-release-wp-plugin |
As with any standard, this helps us address about 80% of use cases.
Avoid repeating and redundant names like satis-satis-satis or cf-worker-workers for a monorepo of workers.
Just satis or cf-workers or cf-workers-{proxies|notifications} suffice.
Our scaffolding-templates don't have just one platform or type, so both prefixes are dropped.
For the greatest evergreen resiliancy, we typically avoid prescribing features to specific brands, even if they're only used on a subset. This way, if another brand needs that feature, we're not putting a {brand}-{feature} into a different brand.
| Avoid | Preferred |
|---|---|
wp-module-bluehost-staging |
wp-module-staging |
webpack-plugin-newfold |
webpack-plugin (@newfold-labs/webpack-plugin) |
wp-module-netsol-sso |
wp-module-sso (with separate netsol file) |
cf-worker-webcom-legacy-compat |
cf-worker-legacy-features (with webcom method, space for others) |
The obvious exception are our "brand plugins" whose sole purpose is serving a single brand like wp-plugin-bluehost.
newfold-labs/{package-name}
Our PHP codebases are often Composer packages we distribute using Satis, and should follow Composer naming conventions.
@newfold-labs/{package-name}
This is essential for GitHub Packages to work correctly.
If JavaScript code is in a monorepo, the top-level config should follow the standard above.
For packages inside the monorepo, they should ideally branch off the top-level config's name.
i.e.
@newfold-labs/node-helpers
@newfold-labs/node-helpers-mustache
@newfold-labs/node-helpers-fs
@newfold-labs/node-helpers-axios
However, as some libraries such as Gatsby rely on package names for some functionality (i.e. gatsby-theme-), those packages are an exception to this standard and should follow the library standards.