Skip to main content

Setup

In this section, we will create a new widget pack project and install all required dependencies.

Requirements​

  • Node.js 20 or later — verify with node --version
  • Git — the CLI uses it to create new projects
  • MoBro installed on the same machine, to test the widget pack
  • An IDE supporting TypeScript and React. This guide uses JetBrains WebStorm, but any other IDE works as well.
No additional npm packages

MoBro compiles widget packs itself and only provides a fixed set of npm packages to them. Installing any other npm package in your project has no effect at runtime.
See Available Packages before you start.

Creating the Project​

First, install the dashboard CLI globally:

npm install --global @modbros/dashboard-cli

The CLI is now available as the dashboard-cli command. Create a new project by running:

dashboard-cli generate my_first_widget_pack

The name may only contain letters, digits, _ and -. The CLI copies the widget pack skeleton into a new my_first_widget_pack directory and initializes a Git repository in it.

Switch to the new directory and install the dependencies:

cd my_first_widget_pack
npm install

Finally, update the SDK packages and the CLI to the versions this documentation describes:

npm install @modbros/dashboard-sdk@^1.4.2 @modbros/dashboard-core@^1.3.0
npm install --save-dev @modbros/dashboard-cli@^1.3.0
note

The installed npm packages only provide types and editor support. At runtime, the dashboard provides these packages. The SDK version in the package.json also defines the minimum SDK version your widget pack requires when published, see Publish and Install.

Project Structure​

After running the commands above, the project looks like this:

my_first_widget_pack
├── .idea/
├── node_modules/
├── src/
├── .editorconfig
├── .eslintrc.json
├── .gitignore
├── .prettierrc
├── mobro-widget-pack-config.json
├── package.json
├── README.md
└── tsconfig.json

src/​

Contains the source code of all widgets, including their configuration files and assets. Only this directory is compiled by MoBro and published to the marketplace.

mobro-widget-pack-config.json​

Required. Contains the metadata of the widget pack, such as its unique name, display name, author and description.

package.json​

Required. Defines the version of the widget pack and the npm packages used for development.

.idea/​

JSON schema mappings for JetBrains IDEs, which provide auto-completion for the configuration files. See JSON Schemas for other IDEs.

Adapting the Configuration​

Next, fill in the information about your widget pack in the mobro-widget-pack-config.json:

mobro-widget-pack-config.json
{
  "name": "my_first_widget_pack",
  "displayName": "My First Widget Pack",
  "description": "Includes my first widgets.",
  "author": "My Company"
}
  • name is the unique identifier of the widget pack in the marketplace. It's not shown to users.
  • displayName is the name shown to users.

This information is visible to users in the marketplace, so choose a meaningful display name and description. All available fields are described in In-depth: Widget Pack Configuration.

caution

The name must be unique across all widget packs in the marketplace, and it can't be changed after the widget pack has been published.

In the package.json, adapt the name, version and description fields to your widget pack. Only change these fields and keep the rest of the file, especially the scripts, dependencies and devDependencies.

The version is used as the version of your widget pack when publishing it to the marketplace.

With that, the project is ready. Next, let's create the first widget.

Last updated on