Matterway

Matterway SDK

APIs, abstractions, helpers and components to develop Skills in no time.

Get started • Documentation • Installation • Development • Contributing • Releases

import * as mw from '@matterway/sdk';

export default function accomplishSomethingStep(ctx: Context) {
  await mw.click(ctx, '.button'); // 😎
}

Get started

If you created your Skill with yarn create, you already have SDK! Just import it and use it:

import * as mw from '@matterway/sdk';

export default function accomplishSomethingStep(ctx: Context) {
  await mw.click(ctx, '.button'); // 😎
}

Otherwise, follow the installation steps.

Documentation

You can learn the basics by following the tutorial.

Most SDK exports provide tsdoc with explanation and examples, which you can access from your editor's intellisense, or at sdk.docs.matterway.io.

Installation

Login to the Matterway Package Registry:

npx verdaccio-auth0-ui --registry https://registry.matterway.io

Add SDK as a dependency of your Skill project:

yarn add @matterway/sdk

Update your src/components/index.ts to export SDK components:

export * from '@matterway/sdk/lib/components';

And you're ready to get started!

Development

To develop on SDK, make a local fork:

git clone git@github.com:matterway/mw-assistant-sdk.git
cd mw-assistant-sdk
yarn
yarn test

Start the dev-server, which rebuilds on change:

yarn build:dev

Testing

Run the test suite:

yarn test

Link your local SDK to test your changes in a Skill:

# In your terminal install globally yalc
yarn global add yalc

# In SDK (In case there are already skills linked to it updates multiple projects sequentially)
yarn link:local

# In your skills
yalc add "@matterway/sdk"

yarn start

⚠️ TODO: ADDING TESTS

Contributing

Contributions are not only appreciated, but encouraged. In practice, they are mandatory.

Read this guide before opening a Pull Request.

Prepare a branch for your changes

Usually you want to branch off latest master:

git checkout master
git pull

Create a branch to contain your changes, including a Github Issue ID from this repo:

                      ↓type ↓gh ↓summary
git checkout --branch chore/123-refactor-watcher

Mark the type of change according to Conventional Commits:

  • fix/123-fix-language-detection
  • feat/123-add-log-helpers
  • chore/123-refactor-watcher
  • docs/123-add-examples

Contribute to an existing package

⚠️ TODO: REFACTOR SECTION

  • Add code that re-composes, modifies or creates helpers.

  • Add documentation in the form of ts-docs (new component also requires a storybook story and documentation)

  • Add debug logs

    Debug logs will allow users to understand what's going on internally, and serves as an invaluable debugging tool.

        function yourHelper(ctx, ...args){
            console.debug('[SDK]', 'yourHelper: called with', {args});

            ...

            console.debug('[SDK]', 'yourHelper: resolved with', {result});
        }

  • Add unit tests where necessary and make sure they pass.

  • Submit a pull request to the master branch.

Components have to be re-exported within the skill to support rendering with the Background Component

  • src/components.ts
  • within this file, re-export the components exported by the package e.g
export * from './sdk-<your-package-name>/components';

Building SDK docs. The SDK documentation site update is triggered by merging into the master branch of the repo.

TBD: @experimental tag

Contribute a new package

⚠️ TODO: REFACTOR SECTION

A package holds a collection of helpers. There currently isn't a specification of what qualifies as a package, but the spirit of it is exemplified by the packages already provided. To put words to these examples, a package is a set of related helpers that tackle a particular skill development domain that is not quite described by the packages already provided .

Hence, before contributing a new package, an action that'll help maintain the integrity of this definition, is to look through the packages to find if the helpers you aim to encapsulate are not described by the packages already provided.

SDK documentation

SDK documentation is generated by yarn build:docs. After documentation was built run yarn serve-docs to spin up a local preview.

Commit and push changes

You can commit and push to your branch at any time. You're encouraged to do it regularly, to checkpoint your work, and avoid losing it accidentally.

You can use amend, rebase, and push -f to keep your history clean.

If you can, you're encouraged to split your change into multiple commits, or multiple PRs, which will make the review process easier.

Pushing will trigger a build (but not a release). You can run tests locally to make sure the build will pass:

yarn test

Submitting for review

Once your changes are ready for review, create a PR, and seek approval from your peers and the Elders.

You can push early to seek early feedback. Mark your PR as draft.

⚠️ TODO: ADD GUIDELINES

Merging

Once the review is accepted, squash or fast-forward. Never push merge commits.

This project obeys Semantic Versioning, and the extent of each change is marked using Conventional Commits:

↓type ↓pr ↓summary ↓issue
fix(progress)!: #456 change failure behavior. fixes #123
↑scope ↑breaking!

type marks the extent of the change. ! marks a breaking change and a major bump:

Type Version bump Release action
fix() Fix a bug in a backwards-compatible way Patch -.-.+1 Release sdk
feat() Add a feature in a backwards-compatible way Minor -.+1.0 Release sdk
fix()! Fix a bug but break compatibility with existing code Major +1.0.0 Release sdk
feat()! Add a feature but break compatibility with existing code Major +1.0.0 Release sdk
chore() Clean-up, refactor, tweak builds, without changing any externally-visible behavior
docs() Updates to docs, README, ... Release sdk-docs

Example:

fix(progress)!: change failure behavior #789

The dev-server does not always restart

Run yarn build:dev this way, until we fix this:

yarn global add nodemon
nodemon --ext 'js,json,ts,tsx' --exec 'yarn build:dev'

Can I change the file watch delay?

You can set it in the root package.json.

Storybook

Is generated automatically and published to https://design.matterway.io/ public/index.html is the entry point for storybook template

SDK with ADS integrated:

If you want to use version of SDK with ADS integrated you need to make few changes in your project.

  • change import of root in content to
import {Root as DesignSystemRoot} from '@matterway/sdk/lib/assistant-design-system/providers/Root/index';
  • remove assistant-design-system from dependencies
   "@matterway/assistant-design-system": "^6.6.0",
  • make sure types are version 10.0.2 or higher:
   "@matterway/types": "^10.0.2",
  • update your exports in components/index.ts from:
export {Text} from '@matterway/sdk/assistant-design-system';

to:

export {Text} from '@matterway/sdk/lib/assistant-design-system';
  • update imports in your custom components from:
import {Text} from '@matterway/sdk/assistant-design-system';

to:

import {Text} from '@matterway/sdk/lib/assistant-design-system';
  • if you work with local version of SDK you need to use yarn link:local, not yarn link, in order to work with yalc

Settings

Theme

On This Page

Get startedDocumentationInstallationDevelopmentTestingContributingStorybookSDK with ADS integrated: