/create-adapter

Command line utility to create customized ioBroker adapters

Primary LanguageTypeScriptMIT LicenseMIT

 ioBroker adapter creator

Command line utility to quickly create a new adapter or VIS widget for ioBroker:

node npm Build Status License Changelog

Prerequisites

Any computer with NodeJS in version 8 or higher and npm 6 or higher.

Usage

This tool is not supposed to be installed. Instead, run the most recent version using

npx @iobroker/create-adapter [options]

in the directory where the directory of your project should be created. You don't need to create the adapter/widget directory, because it will be created for you. WARNING: If the path contains a space, this won't work.

After a short while, you will be asked a few questions. Afterwards all the necessary files will be created for you.

Options

The following CLI options are available:

  • --target=/path/to/dir - Specify which directory the adapter files should be created in (instead of the current dir). Shortcut: -t
  • --skipAdapterExistenceCheck - Don't check if an adapter with the same name already exists on npm. Shortcut: -x
  • --replay=/path/to/file - Re-run the adapter creator with the answers of a previous run (the given file needs to be the .create-adapter.json in the root of the previously generated directory). Shortcut: -r
  • --migrate=/path/to/dir - Run the adapter creator with the answers pre-filled from an existing adapter directory (the given path needs to point to the adapter base directory where io-package.json is found). Shortcut: -m

All CLI options can also be provided as environment variables by prepending CREATE_ADAPTER_. Example: CREATE_ADAPTER_TARGET=/tmp/iobroker/create-adapter/

Features

  • Choose between: ioBroker adapter, VIS widget or both
  • Ask for package metadata (with automatic translation):
    • Title (mandatory)
    • Short description (optional)
    • Adapter start mode
    • Adapter/VIS category
    • Keywords (optional)
  • IntelliSense (auto completion and tooltips) in supporting editors based on the ioBroker declaration files
  • JavaScript with the following optional tools:
    • ESLint for code quality
    • Type checking based on the ioBroker declarations, including strongly-typed adapter.config properties
  • Or TypeScript with the following optional tools:
    • ESLint for code quality
    • Automatic formatting with Prettier
    • nyc for code coverage
    • strongly-typed adapter.config properties
  • Choose between indentation: tabs or 4 spaces
  • Choose your preferred quote style
  • Integration in the ioBroker admin UI:
    • Settings page
    • An extra tab (optional)
    • Custom datapoint-specific options (optional)
  • React as an alternative to plain HTML+CSS for the admin and extra tab UI, based on @iobroker/adapter-react
  • Predefined settings page for the admin UI
  • Choice of an OpenSource license and automatic creation of the license file
  • Built-in component tests using mocha, chai (with chai-as-promised) and sinon (with sinon-chai) for:
    • Correctly defined package files
    • and your own tests...
  • Automated testing using Github Actions or Travis CI, including a script for semantic release of new versions

Developing

First of all: DO NOT push changes to master directly! Just don't. Every change should be done through PRs, which have a template with a checklist to fill out. This makes sure that master always works and every change is documented.

For developers of this package, there are a few things to know:

  • npm run build creates a fresh build and deletes old build files. This is necessary when template files are renamed or deleted, as the compiled files will still be there.
  • npm run watch keeps compiling incremental changes whenever you save a source file.
  • The directory /templates contains a bunch of templates, which are basically TypeScript files exporting a single method:
    • This method accepts an object with the user's answers and returns a string or Promise<string> containing the output file.
    • The last extension (.ts) is removed when creating the output file. Setting the customPath property of the template method allows you to override the output path of the file, either a constant or depending on the user's answers (function).
    • The outputted files are automatically formatted to have the correct indentation and multiple empty lines are removed. If you don't want this, set noReformat to true.
  • Test your changes with npm test and/or write relevant tests. For a couple of representative combination of answers, baseline adapter directories are generated. If those baselines are changed as a result of your changes, please review if those changes are desired.

Publishing

Do not publish directly using npm. Instead create a new release with the release script npm run release .... This creates a tag on github, performs a test run on TravisCI and after a successful build automatically publishes to npm.

You can semantically increase the version and publish it by using

npm run release [<releaseType> [<postfix>]] [-- --dry]

(preferably) or set a specific version by using

npm run release <version> [-- --dry]

The option -- --dry (don't forget the first pair of dashes) performs a dry run without updating files. The available release types are:

  • major
  • premajor
  • minor
  • preminor
  • patch
  • prepatch
  • prerelease

and the pre-... versions allow you to append a postfix like -beta.