Configuring Packages
All configuration of the package is located in the package.json
file. This is a node package file following NPM’s conventions.
Example
Here is a minimal example:
package.json
{
"name": "@awesome/package",
"version": "0.1.0",
"keywords": ["webwriter-widget"],
"script": {
"prepublishOnly": "npx @webwriter/build"
},
"exports": {
"./widgets/awesome-widget.*": {
"source": "./src/widgets/awesome-widget.ts",
"default": "./dist/widgets/awesome-widget.*"
},
}
}
Required fields
name
Must be a scoped package name, e.g. @org/pkg
. The scope of the package (e.g. org
) will also be the prefix of your widgets (meaning in a package @foo/bar
, widgets must be named foo-mywidget
, foo-anotherwidget
, and so on). You are responsible to avoid name collisions between widgets within the org
(e.g. two widgets named foo-mywidget
).
version
Must be a SemVer 2 version identifier (MAJOR.MINOR.PATCH
). Versions with major version 0
(e.g. 0.1.0
) are considered as pre-release and are hidden by default when users search for packages.
Rules for updating
You should stick to some rules so WebWriter can automatically update explorable to new widget versions while staying backwards-compatible:
- Increment
MAJOR
for breaking attribute, event or editing config changes. IncrementMINOR
when adding attributes, events, or making compatible editing config changes. IncrementPATCH
when nothing about the interface of the widget has changed. - Use versions starting with
0
as pre-release versions that should be hidden from most users.
keywords
Each WebWriter widget must have the webwriter-widget
keyword so it can be found and installed. It is recommended you add additional keywords to describe your widget further.
exports
The exports
field is an object mapping an exported name to a file path. There are three types of exports: Widgets, snippets and themes. Each should be exported according to the following example:
Full format for @webwriter/build
{
"name": "@awesome/package",
"version": "0.1.0",
"keywords": ["webwriter-widget"],
"exports": {
"./widgets/awesome-widget.*": {
"source": "./src/widgets/awesome-widget.ts",
"default": "./dist/widgets/awesome-widget.*"
},
"./snippets/awesome-snippet.html": "./src/snippets/awesome-snippet.html",
"./themes/awesome-theme.html": "./src/themes/awesome-theme.css"
}
}
Optional fields
Extra metadata: description
, author
/contributors
, license
The description
is a short text describing the widget in English. This is shown to the user when browsing packages and also used for package search. The author
and/or contributors
fields are used to specify people involved (see here). The license
is an SPDX license identifier.
{
// ...
"description": "Offers awesome functionality such as ...",
"author": "John Doe <doe@example.com>",
"license": "MIT"
}
editingConfig
The editing config allows you to configure how WebWriter treats your widget, snippet, or theme when editing. More details are found on the respective pages for widgets, snippets, and themes.
Others
All other fields according to NPM’s conventions are allowed, but are generally ignored. dependencies
are installed when the package is installed, while devDependencies
are ignored.