Matterway

Matterway SDK

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

Get started • Documentation • Installation • Development • Contributing • License •

Get started

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

import {click} from '@matterway/sdk';

export default function accomplishSomethingStep(ctx: Context) {
  await 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 learn.matterway.

Installation

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/message/components';
export * from '@matterway/sdk/lib/progress/components';
export * from '@matterway/sdk/lib/form/components';
export * from '@matterway/sdk/lib/notice/components';
export * from '@matterway/sdk/lib/file/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 build:sdk

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:

# Create SDK tarball
yarn build:sdk && yarn pack

# In your skills, update package.json to point to the tarball
# (Make sure the path starts with file:/)
"dependencies": {
  "@matterway/sdk": "file:/../path/to/@matterway-sdk-1.0.0.tgz"
}

# Remember to bump the SDK version if changes were made
# Update the version in the SDK's package.json

# Install dependencies and start the project
yarn install
yarn start

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

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.

Contribute new helpers

If you want to add new functionality, please contribute new helpers or utilities directly to the SDK. Before submitting, review the existing helpers to ensure your addition is not already covered. Make sure to document your helper clearly and provide usage examples where possible.

SDK documentation

SDK documentation is generated by yarn build:docs. After documentation was built run yarn watch: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.

Merging

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

Note: Merging to the main branch will automatically trigger a release of a new alpha version of the SDK.

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

Storybook

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

Running Storybook locally

To preview Storybook locally, you need to first build the static Storybook, then serve it:

Build the static version of Storybook:
```
yarn storybook:build
```
The static build will be output to the ./build/storybook directory.
Serve the built Storybook locally:
```
yarn storybook:serve
```
This will start a local server, usually at http://localhost:9009, where you can view and interact with your components in the browser.

Hot Reload

The SDK provides a <HotReload> component to enable hot-reloading of your Skill’s UI during development. This allows you to see changes instantly without a full page refresh.

Usage

Wrap your main content component with <HotReload> in your content.tsx:

import {HotReload} from '@matterway/sdk/lib/hot-reload/components';
// ...other imports...

root.render(
  <ThemeContextProvider>
    <DesignSystemRoot styleSheetTarget={reactMountRoot}>
      <HotReload>
        <BackgroundContent
          contentComponents={contentComponents}
          onInitialLanguageCodeReceived={(languageCode) => {
            initI18n(languageCode);
          }}
        />
      </HotReload>
    </DesignSystemRoot>
  </ThemeContextProvider>,
);

This setup ensures that UI changes are reflected immediately during development.

Important: To enable hot reload, you must call initSkill in your background.tsx:

import {initTheme, initSkill, type Context} from '@matterway/sdk';
import {initI18n} from 'locales';
import {failure} from 'steps/@failure';
import {start} from 'steps/@start';
import {skillRenderCheck} from 'skillRenderCheck';

export default async function (ctx: Context) {
  console.clear();
  initI18n(ctx.languageCode);
  await initTheme(ctx);

  try {
    await skillRenderCheck(ctx);
    await initSkill(ctx, start);
  } catch (err) {
    console.error(err);
    await failure(ctx, err as Error);
    throw err;
  }
}

Note: Hot reload is intended for development only and has no effect in production builds.

Using Steps

To execute a step in your Skill, use the step helper as shown below:

import {Context, step} from '@matterway/sdk';
import {success} from 'steps/@success';
import {welcomeMessage} from './welcomeMessage';

export async function start(ctx: Context) {
  await step(welcomeMessage, [ctx]);
  await step(success, [ctx]);
}

License

Unauthorized copying, distribution, modification, or use is strictly prohibited without prior written consent from Productive Mobile AWSM GmbH.