Nutmeg icon Nutmeg logo Build, test, and publish vanilla Web Components with a little spice [![Version Status](https://img.shields.io/npm/v/@nutmeg/cli.svg?style=flat&label=version&colorB=4bc524)](https://npmjs.com/package/@nutmeg/cli) [![Build Status](https://github.com/abraham/nutmeg/actions/workflows/index.yaml/badge.svg)](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.