Skip to main content

Structures & Conventions

Repository Conventions​

Our repositories are organized using typical conventions you would find in a modern Javascript/Typescript project, with a package.json, tsconfig.json, and project configuration files in the repository's/package's top directory.

Configuration Files​

Below is a list of configuration files you can expect to find and a little blurb about each one:

  • package.json: stores essential metadata, dependency lists, and occasionally tooling and third-party configurations.
  • tsconfig.json: Typescript configuration file that also helps set global linting rules for the project, as well as define building and bundling configurations for our build processes.
  • biome.json: Biome (linter & formater) configuration file that contains a one liner pointing to the main Biome configuration file in our dev-web-configs package.
  • vite.config.ts: Vite configuration file for compiling browser targeted code.
  • commitlint.config.mjs: Commitlint keeps our commit messages organized with standardized prefix requirements.
  • *.types.ts: This is a file that contains types for a file of the same name. We find that stashing file specific types away into a separate file keeps things tidy.

Configuration Directories​

Below is a list of directories you'll find in our projects and a bit about the contents of each one:

  • .dev: houses build scripts, production files, ci/cd information, and any other development files necessary for the project.
  • .husky: contains configuration files for Husky hooks. These are scripts (linting, formatting, testing, etc) that run on Git commits and pushes to ensure our code is standardized before entering the repository.
  • .forgejo: stores ci/cd scripts compatible with our Forgejo instance.
  • src: stores the main files for building and bundling. It is the default directory that our build scripts will look for when running their processes.
  • packages: monorepo convention for storing multiple packages in a single repository.

Project Scripts​

The following are standardized scripts across our projects that can be ran by running bun <script> in a repository or package's top most folder.

Install​

Running bun i or bun install will install all dependencies needed for the project.

Build​

Running bun run build will initiate the project's build process.

Building is done by either using Bun's native bundler, or Vite for more front-end focused things

Bun Bundler​

When building with Bun's bundler, we run use Bun to execute the build.ts file in the .dev directory that utilized Typescript and Bun's native API to build the project.

Vite​

When building a Component or other front-end focused package with Vite's library mode, the project will use the configuration included in this repository's vite.config.ts file.

Dev​

Running bun dev will start the project's developer/watch mode.

It will typically watch the source directory, and auto-compile your project to it's distribution (./dist) directory.

Custom Scripts​

A project will sometimes contain custom scripts unique to itself or relative group.

Be sure to give the project's package.json a peek to familiarize yourself with the scripts and tools available to you when working with a new repository.

Project Types​

Components​

Front-end Components are modular pieces of code that can be used like custom HTML components in their respected environment. A component is usually a single function containing UX logic that returns JSX.

Typically, our components are built using React. Repositories can either contain one sole component, or export multiple.

Template: https://git.sone.dev/dev/template-web-component

Services​

Services are what you would typically consider a backend application. They run on the edge/a server and often provide data to a front-end.

Most services fall under the category of a REST API or gRPC service that returns a JSON response. For this purpose, we are in love with the Hono framework for it's flexibility and edge first development, while still offering compatibility with a more traditional server architecture if needed.

Template: https://git.sone.dev/dev/template-web-service

Applications​

Applications are services that contain a front-end and are geared towards user interaction instead of CRUD or other backend operations. For this, we're loving React Router in Framework mode.

Template: https://git.sone.dev/dev/template-web-app

Libraries​

Libraries are typically snippets of code that offer an array of utilities for a specified purpose or project.

They are traditionally exported functions that offer repeatable logic to projects. Examples may include color conversion utilities, database driver connections, etc.

Template: https://git.sone.dev/dev/template-web-lib

Monorepos​

Monorepos are repositories that contain a related mixture of project repositories in a subfolder.

They contain most top level project files, with the exception of a ./src directory. A ./packages folder can be found containing the associated projects for the repository.

Template: https://git.sone.dev/dev/template-web-monorepo

Naming Conventions​

We prioritize keeping names concise and human readable. When in doubt: don't think too much about it and err on the side of readability.

Repository Names​

Our aim is to keep repositories readable and self explanatory.

template-web-component
web-configs
tone

Component Names​

Component file names and functions always begin with a capital letter and follow CamelCase.

UserCreationForm.tsx
export function UserCreationForm()

Typography.tsx
export function Typography()
info

Reminder that Component files contain JSX and therefore require a .tsx extension.

Function Names​

Functions are typically in camelCase and start with a lowercase first letter.

buildProject()
createWorldPeace()
getUniversalKnowledge()
endAllSufferingWithSomeExceptions()

Versioning​

We use semantic versioning for our standards.

<major>.<minor>.<release>.<hotfix>
  • Major: Signifies a big milestone release or indicates a breaking change.
  • Minor: Typically contains a new feature, light clean up, or small refactor.
  • Patch: Contains a fix for the current minor version
  • Hotfix: Indicates a critical fix that was released outside of the typical release cycle. (optional)