Naming projects

The platform-type-name convention for repositories, Composer packages and npm packages

Id general-naming-projects Applies to any Status active Enforceable yes, no check yet Tags namingrepositoriescomposernpm

Naming projects well from the beginning can prevent lots of labor to correct down the line. Many projects grow to accommodate 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.

This list is not comprehensive.

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 resiliency, 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.

For example:

@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.