Package Development

Welcome to the package development guide for NOBEARS frontend packages. This documentation covers our standardized approach to developing, maintaining, and releasing frontend packages.

Overview

At NOBEARS, we maintain several types of packages:

• UI Components: Design systems and reusable interface elements (@nobears-front-end/nuxt-ui)
• Framework Integrations: Modules for Nuxt, Statamic, etc. (@nobears-front-end/nuxt-statamic)
• Utility Libraries: Shared functions and tools

What You'll Learn

This guide will walk you through:

• Creating new packages using our starter templates
• Following our code standards and naming conventions
• Managing package versions and releases
• Writing and maintaining documentation
• Ensuring code quality through testing

Whether you're building a new package or maintaining an existing one, this guide ensures you follow our best practices and workflows.

Package Types

Before we get started, let's take a look at the different types of packages we maintain.

1. Layers
   Layers are specificly used in Nuxt projects, they are used to add extendable and overrideable code to your project. @nobears-front-end/nuxt-ui is a great example of this.
2. Modules
   Modules are used to add framework or tool specific code to your project, e.g. @nobears-front-end/nuxt-statamic is a module for the Statamic CMS integration.
3. Packages
   Packages are the simplest type of package, they are used to simple and extendable code that is not framework or tool specific. A ESlint config is a great example of this.
4. Templates
   In order to keep it easy for developers to get started, we have created a set of starter templates. We have templates for starting a new package, a new project and more.

Creating a new package

Before you start creating a new package, you should first check with other developers if the package is not already created or if it's not already in the process of being created. If you can't find a package that fits your needs, you can create a new one (if you have permission to do so of course).

We use a Jira board to keep track of all the packages we maintain, if you need to create a new package, please create a new ticket in Jira in order to get the process started. From there you should start by describing the package you want to create, what it will be used for and what it will contain.

Once you have the green light from the team, you can start by creating a new package.

Naming Convention

• Format: @nobears-front-end/<tech-stack>-<package-name>
• Examples:
  • @nobears-front-end/nuxt-ui
  • @nobears-front-end/nuxt-statamic
  • @nobears-front-end/statamic-template

If we take a look at the nuxt-statamic package, you'll notice that it has 2 frameworks/ tech stacks in the name. This is because it's a package that is used to integrate Statamic with Nuxt, in these cases it's best to use the naming convention <tech-stack-of-the-project>-<tool-or-integration-name>.

Versioning

• Follow Semantic Versioning
• Format: MAJOR.MINOR.PATCH
• Beta releases: 1.0.0-beta.1

Required Files

• package.json: Package configuration
• README.md: Package documentation
• CHANGELOG.md: Version history
• tsconfig.json: TypeScript configuration
• types/: TypeScript types (we prefer to use .ts files instead of .d.ts files)
• test/: Test files (if applicable)

Documentation

Adding documentation to your package is done by adding a docs folder to the root of your package.

This folder will be read by our frontend doc, thus automatically adding your package to the general documentation site.

• Place documentation in docs/ directory
• Include:
  • Getting started guide
  • API reference
  • Examples

(Git) workflow

If you want to get started with working on a new feature, the first thing you should do is create a new ticket in the Jira board. Before you start working on a new feature, it must first be approved by the team. When you have the green light, you can start by creating a new branch.

Branches

If you are working on a Jira ticket, you should create a new branch based on the preview branch, using the following naming convention: story/FE-{ticket-id}.

Commits

In order to correctly manage the changelog, we have a set of commitlint rules that are used to ensure the commit messages are correct for the changelog.

Creating a commit

To create a commit, use the following command:

pnpm commit

Or you can use the following command to commit all changes:

pnpm commit:all

This will open a prompt to help you write a commit message that adhears to the commitlint rules.

Commit types

The following commit types will not be automatically added to the changelog in order to keep the changelog clean and readable:

Releasing a package

We follow a structured release process to ensure quality and stability across both beta and stable releases. Specifically, we use release-it to release new versions of our packages.

It is a requirement that you use the correct commit message syntax. If you skip this step, we can't properly update the changelog.

Releasing a beta version

You will most likely never be in a situation where you need to release a beta version, since small changes are mostly released as a patch version.

Skip to 'releasing a stable version' if you don't need to release a beta version.

But since there are some cases where it is needed, we have the following process for it:

pnpm commit

pnpm release-beta

Releasing a stable version

pnpm release