Build, test, and publish vanilla Web Components with a little spice
[](https://npmjs.com/package/@nutmeg/cli)
[](https://github.com/abraham/nutmeg/actions/workflows/index.yaml)
๐ง _Nutmeg is in active development and it's APIs are still in flux._
## ๐ Overview
Nutmeg is here to help you build, test, and publish Web Components in minutes.
By default you get the following:
- Custom Elements v1
- Shadow DOM v1
- TypeScript
- LitElement
- Vitest browser mode test runner with headless Chromium
- Git
- MIT license
- Web Component best practices
## ๐ฑ Build
Generating a Nutmeg Web Component skeleton with [npm init](https://docs.npmjs.com/cli/init) has the API ` [property:type...]`.
```bash
npm init @nutmeg hello-world name:string
```
This will create a `hello-world` directory, stub out a base Web Component class `HelloWorld` that extends the Nutmeg `Seed` base class, and install the default dependencies. You can use either `fullName` or `full-name` for multi-word properties and `full-name` will be used for HTML attributes and `fullName` will be used in JavaScript.
_Note: Yarn is not supported but may work._
### ๐ก Properties
Properties must be valid TypeScript types. For example `string`, `boolean`, `number`, `string[]`, `Element`.
```bash
npm init @nutmeg grilled-cheese quantity:number pickles:boolean cheese:string[]
```
Properties are the public API of your Web Component and external code can set/get them.
```javascript
export class GrilledCheese extends Seed {
@property() accessor bread: string;
@property() accessor cheese: string[];
@property() accessor pickles: boolean;
@property() accessor quantity: number;
...
}
```
The `@property()` decorator provides some nice features out of the box. There are two kinds of properties.
- Primitive: `boolean`, `string`, and `number`.
- Complex: any types that are not primitive.
#### โ๏ธ Automatic rendering
Any properties decorated with `@property` will automatically render when set.
#### ๐ Primitive properties are reflected to the DOM
- **boolean**: `grilledCheese.pickle = true;` => ``
- **number**: `grilledCheese.quantity = 5;` => ``
- **string**: `grilledCheese.bread = 'sourdough';` => ``
#### ๐ฑ One-time complex property loading from attributes
On instantiation of a Web Component a one-time loading and JSON parsing happens of complex properties. In the following example `cheese` has the type of `string[]`. When connected the component will have the attribute removed and the value set as a property after `JSON.parse`.
The following example:
```html
```
Yields:
```javascript
grilledCheese.cheese.includes('sharp cheddar') === true;
```
```html
```
#### `$` and `$$`
`$` and `$$` are shortcuts provided for quickly selecting elements within the shadowRoot.
- `$` is a shortcut for `this.shadowRoot.querySelector`.
- `$$` is a shortcut for `this.shadowRoot.querySelectorAll`.
### ๐ฝ๏ธ Serve
You can now serve the component for development on http://localhost:8080 by running:
```bash
npm start
```
With `start` running you can make edits to the component and see the changes take effect automatically without manually refreshing.
## ๐งช Test
Running the tests from within `hello-world`.
```bash
npm test
```
### ๐ญ Continuous Integration
Components are generated with a [GitHub Actions](https://github.com/features/actions) workflow pre-configured to run tests on Windows, macOS, and Linux.
## ๐๏ธ Publish
Publishing to NPM is easy but make sure you are logged in first with `npm login`. Be sure to fill out `package.json` values like author and update the name in `readme.md` if you change it.
```bash
npm publish
```
### ๐ Dependencies
Components are generated with a [Dependabot](https://docs.github.com/en/code-security/dependabot) config to keep your dependencies current.
## ๐ Best practices
Out of the box many of the [Google Web Fundamentals Custom Element Best Practices](https://developers.google.com/web/fundamentals/web-components/best-practices#place-any-children-the-element-creates-into-its-shadow-root) are handled automatically.
## ๐ Examples
- [HelloWorld](https://github.com/abraham/nutmeg-hello-world) built using `nutmeg new hello-world name:string`.
- [TwitterStatus](https://github.com/abraham/twitter-status) for embedding tweets.
## ๐ License
Nutmeg is released under an MIT license.