Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/abraham/nutmeg
Build, test, and publish vanilla Web Components with a little spice
https://github.com/abraham/nutmeg
cli custom-elements hacktoberfest javascript karma lit-element lit-html shadow-dom typescript web-components webcomponents webpack
Last synced: 2 days ago
JSON representation
Build, test, and publish vanilla Web Components with a little spice
- Host: GitHub
- URL: https://github.com/abraham/nutmeg
- Owner: abraham
- License: mit
- Created: 2017-08-30T11:10:36.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-06-16T14:28:29.000Z (6 months ago)
- Last Synced: 2024-12-18T06:05:18.717Z (9 days ago)
- Topics: cli, custom-elements, hacktoberfest, javascript, karma, lit-element, lit-html, shadow-dom, typescript, web-components, webcomponents, webpack
- Language: TypeScript
- Homepage: https://nutmeg.dev
- Size: 4.5 MB
- Stars: 115
- Watchers: 9
- Forks: 8
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-web-components - nutmeg - Build, test, and publish vanilla Web Components with a little spice. (Meta Frameworks / Starter Kits)
README
Build, test, and publish vanilla Web Components with a little spice
[](https://npmjs.com/package/@nutmeg/cli)
[](https://circleci.com/gh/abraham/nutmeg)
[](https://travis-ci.org/abraham/nutmeg)
[](https://ci.appveyor.com/project/abraham/nutmeg)
[](https://david-dm.org/abraham/nutmeg)
🚧 _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
- lit-html
- Karma test runner with headless browser launchers
- 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() public bread: string;
@property() public cheese: string[];
@property() public pickles: boolean;
@property() public 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 [AppVeyor](https://www.appveyor.com/), [CircleCI](https://circleci.com/), and [TravisCI](https://travis-ci.org/) pre-configured to run tests on Windows, macOS, and Linux respectively.
## 🗞️ 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
Once published, it's recommended that you set up [Renovate](https://renovateapp.com/) to keep your dependencies current. Nutmeg has already setup a default renovate config for you, you just have to [install the free GitHub app](https://github.com/apps/renovate).
## 😎 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.