Conventions

You're not required to follow these conventions; they're simply a standard set of practices used in the core kit. If you like them, we encourage you to keep them during your usage of the kit so you have a consistent code style that you and your teammates understand.

Turborepo packages

In this project, we use Turborepo packages to define reusable code that can be shared across multiple applications.

Apps are used to define the main application, including routing, layout, and global styles.
Packages share reusable code and add functionality across multiple applications. They're configurable from the main application.

Should I create a new package?

Recommendation: Do not create a package for your app code unless you plan to reuse it across multiple applications or are experienced in writing library code.

If your application is not intended for reuse, keep all code in the app folder. This approach saves time and reduces complexity, both of which are beneficial for fast shipping.

Experienced developers: If you have the experience, feel free to create packages as needed.

Imports and paths

When importing modules from packages or apps, use the following conventions:

From a package: Use @workspace/package-name (e.g., @workspace/ui, @workspace/api, etc.).
From an app: Use ~/ (e.g., ~/components, ~/config, etc.).

Enforcing conventions

We don't enforce complex rules or specific style guides that are not relevant to the project, giving you more freedom to customize things to your needs.

To enforce these conventions, we use the following tools:

Oxfmt is a Prettier-compatible tool used to enforce code formatting.
Oxlint is an ESLint-compatible tool used to enforce code quality and best practices.
TypeScript is used to enforce type safety.

Oxfmt

oxc.rs

Oxlint

oxc.rs

TypeScript

typescriptlang.org

Code health

TurboStarter provides a set of tools to ensure code health and quality in your project.

GitHub Actions

By default, TurboStarter sets up GitHub Actions to run tests on every push to the repository. You can find the workflow configuration in the .github/workflows directory.

The workflow has multiple stages:

format - runs Oxfmt to format the code.
lint - runs Oxlint to check for linting errors.
test - runs tests.

Git hooks

Together with TurboStarter, we have set up a pre-commit hook that will check for linting and formatting errors in the files being committed.

It's configured using Lefthook, which supports multiple hooks and can be configured to run commands on specific files or directories.

Feel free to customize the hook to your needs, e.g. to check consistency of commit messages (useful for generating changelogs) using commitlint:

lefthook.yml

commit-msg:
  commands:
    "lint commit message":
      run: pnpm commitlint --edit {1}