Naming Projects
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.
All packages should match their repository name
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).
Standard
In lieu of fancy codenames and clever, aspirational abstracts, we largely follow the following convention:
{platform}-{type}-{name}
We have prescribed prefixes for many of our Common Product Conventions below.
Please keep reading to understand when platform and type conditionally apply.
Platform
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 |
Type
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.
Name
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 |
Notable Exceptions
As with any standard, this helps us address about 80% of use cases.
Redundancies
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.
Cross-platform repositories
Our scaffolding-templates don’t have just one platform or type, so both prefixes are dropped.
Generally we avoid brand, company and team names in platforms
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.
Composer Packages
Standard
newfold-labs/{package-name}
Our PHP codebases are often Composer packages we distribute using Satis, and should follow Composer naming conventions.
JavaScript Packages
Standard
@newfold-labs/{package-name}
This is essential for GitHub Packages to work correctly.
Note on Monorepos
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.