---

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

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

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'); // 😎
}
Copy

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
Copy

Add SDK as a dependency of your Skill project:

yarn add @matterway/sdk
Copy

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

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

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
Copy

Start the dev-server, which rebuilds on change:

yarn build:dev
Copy

Testing

Run the test suite:

yarn test
Copy

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

# Create SDK tarball
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

Copy

⚠️ 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
Copy

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
Copy

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});
  	}
  Copy

• 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';
Copy

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
Copy

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!
Copy

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
Copy

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'
Copy

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';
Copy

• remove assistant-design-system from dependencies

   "@matterway/assistant-design-system": "^6.6.0",
Copy

• make sure types are version 10.0.2 or higher:

   "@matterway/types": "^10.0.2",
Copy

• update your exports in components/index.ts from:

export {Text} from '@matterway/sdk/assistant-design-system';
Copy

to:

export {Text} from '@matterway/sdk/lib/assistant-design-system';
Copy

• update imports in your custom components from:

import {Text} from '@matterway/sdk/assistant-design-system';
Copy

to:

import {Text} from '@matterway/sdk/lib/assistant-design-system';
Copy