Skip to content
Design System

sdk

Atruvia Extensions SDK

This repository contains the Atruvia Extensions SDK, which provides tools and libraries for developing extensions for Atruvia’s software ecosystem.

Installation

To install the SDK, use the following command:

Terminal window
pnpm add @mmm/sdk

To allow Bitbucket Pipelines to install during CI builds, you need to add a NPM_AUH_TOKEN to repository variables.

You find NPM_AUTH_TOKEN in 1Password. Ask the dev-team for details.

  1. Go to Bitbucket Repository Settings.
    1. Pipelines > Repository variables
    2. Add NPM_AUTH_TOKEN to variables
  2. Source private registry in the script section of a step in the pipeline using npmrc: 
    script:
      - echo "Pull Request Build"
      - corepack enable
      - printf "@mmm:registry=https://npm.dev.appcenter.de\n" > .npmrc.ci
      - printf "registry=https://registry.npmjs.org/\n" >> .npmrc.ci
      - printf "always-auth=true\n" >> .npmrc.ci
      - printf "//npm.dev.appcenter.de/:_authToken=%s\n" "${NPM_AUTH_TOKEN}" >> .npmrc.ci
      - NPM_CONFIG_USERCONFIG="$PWD/.npmrc.ci" pnpm install
      - NPM_CONFIG_USERCONFIG="$PWD/.npmrc.ci" pnpm run build
      - rm .npmrc.ci
  3. Done!

Now your CI builds should be able to install the SDK without any issues.

Usage

After installing the SDK, you can import and use its.

The following modules are exported:

  • @mmm/sdk: Core functionalities of the SDK.
  • @mmm/sdk/vue: Vue.js composables and components.
  • @mmm/sdk/styles: SASS mixins and utilities.
  • @mmm/sdk/eslint: ESLint configurations and plugins.
  • @mmm/sdk/vite: Vite plugins.
  • @mmm/sdk/types: TypeScript global types.
  • @mmm/sdk/src: All runtime code (not recommended for direct use).
import { SomeModule } from '@mmm/sdk';
import { AnotherModule } from '@mmm/sdk/vue';

In .scss files, you can import the styles like this:

@use '@mmm/sdk/styles/utils';
@use '@mmm/sdk/styles/media';

Documentation

For an overview of the available JS features use the CLI help:

Terminal window
pnpm sdk docs

Development

The SDK consists of multiple packages.

  • /src: Runtime functions and services.
  • /src/vue: Vue.js specific composables and components.
  • /types: TypeScript global types.
  • /styles: SASS mixins and utilities.
  • /resources/eslint: ESLint configurations and plugins.
  • /resources/vite: Vite configurations and plugins.
  • /bin: CLI entry point.
  • /scripts: Build scripts for the SDK.
  • /docs: Documentation source files - autogenerated by documentation.js from the source code.
  • /dist: Compiled output files.

To build the SDK, run:

Terminal window
pnpm build

PR

Use PR for big features to allow other developers review, talk about and approve the new feature.

What happens when you push onto any pull-request:

  1. The pipeline runs linting and tests.
  2. The pipeline runs the build, so a broken build shows up before the merge.

Publishing

A release tag triggers publishing, not a push to main. The tag carries the version, so nothing is derived while publishing.

What happens when you push onto main:

  1. The pipeline runs linting and tests.
  2. The pipeline runs the build.

What happens when you push a tag matching v*:

  1. The pipeline runs linting and tests.
  2. The pipeline runs the build and hands dist to the next step as an artifact.
  3. The pipeline publishes dist under the version of the tag.

Publishing stops when the tag version and the version in package.json differ. That catches a tag on the wrong commit.

Commit Message Guidelines

Version bumps are determined by the commit messages since the last git tag:

See Conventional Commits for a complete overview of the specification.

Example commit messages:

  • feat!: add a breaking change (major version bump)
  • feat: add new feature (minor version bump)
  • fix: fix a bug (patch version bump)
  • chore: update dependencies (patch version bump)

Bitbucket writes Merged in <branch> (pull request #N) as the subject of a squash merge and keeps the typed commits in the body. The bump therefore comes from the full message, subject and body. Without any conventional commit the version falls back to a minor bump.

Releasing a new version

Run this on an up to date main:

Terminal window
pnpm release:version

It runs the tests, determines the bump, writes package.json and CHANGELOG.md, creates the release commit and tags it. Use -v major|minor|patch or -v v1.2.3 to override the derived bump, and --dryRun to see the outcome without writing.

Push the commit and the tag to release:

Terminal window
git push --follow-tags

Pass --push to pnpm release:version to let the script push instead.

Tools used