Awesome Open Source
Awesome Open Source
Nutmeg icon Nutmeg logo

Build, test, and publish vanilla Web Components with a little spice

Version Status macOS Build Status Linux Build Status Windows Build Status Dependency Status

๐Ÿšง 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
  • Webpack
  • Karma test runner with headless browser launchers
  • Git
  • MIT license
  • Web Component best practices

๐ŸŒฑ Build

Generating a Nutmeg Web Component skeleton with npm init has the API <element-name> [property:type...].

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.

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.

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; => <grilled-cheese pickle></grilled-cheese>
  • number: grilledCheese.quantity = 5; => <grilled-cheese quantity="5"></grilled-cheese>
  • string: grilledCheese.bread = 'sourdough'; => <grilled-cheese bread="sourdough"></grilled-cheese>

๐Ÿ“ฑ 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:

<grilled-cheese cheese="[\"sharp cheddar\"]"></grilled-cheese>


grilledCheese.cheese.includes('sharp cheddar') === true;

$ 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:

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.

npm test

๐Ÿ”ญ Continuous Integration

Components are generated with AppVeyor, CircleCI, and TravisCI 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 if you change it.

npm publish

๐Ÿ“‡ Dependencies

Once published, it's recommended that you set up Renovate to keep your dependencies current. Nutmeg has already setup a default renovate config for you, you just have to install the free GitHub app.

๐Ÿ˜Ž Best practices

Out of the box many of the Google Web Fundamentals Custom Element Best Practices are handled automatically.

๐Ÿ” Examples

๐Ÿ‘” License

Nutmeg is released under an MIT license.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,541,314)ย 
Typescript (247,386)ย 
Cli (15,155)ย 
Webpack (9,669)ย 
Webcomponents (2,085)ย 
Webcomponents (2,085)ย 
Custom Elements (589)ย 
Karma (405)ย 
Lit Html (210)ย 
Shadow Dom (150)ย 
Related Projects
Advertising ๐Ÿ“ฆย 9
All Projects
Application Programming Interfaces ๐Ÿ“ฆย 120
Applications ๐Ÿ“ฆย 181
Artificial Intelligence ๐Ÿ“ฆย 72
Blockchain ๐Ÿ“ฆย 70
Build Tools ๐Ÿ“ฆย 111
Cloud Computing ๐Ÿ“ฆย 79
Code Quality ๐Ÿ“ฆย 28
Collaboration ๐Ÿ“ฆย 30
Command Line Interface ๐Ÿ“ฆย 48
Community ๐Ÿ“ฆย 81
Companies ๐Ÿ“ฆย 60
Compilers ๐Ÿ“ฆย 60
Computer Science ๐Ÿ“ฆย 74
Configuration Management ๐Ÿ“ฆย 39
Content Management ๐Ÿ“ฆย 167
Control Flow ๐Ÿ“ฆย 197
Data Formats ๐Ÿ“ฆย 77
Data Processing ๐Ÿ“ฆย 266
Data Storage ๐Ÿ“ฆย 132
Economics ๐Ÿ“ฆย 60
Frameworks ๐Ÿ“ฆย 198
Games ๐Ÿ“ฆย 122
Graphics ๐Ÿ“ฆย 103
Hardware ๐Ÿ“ฆย 148
Integrated Development Environments ๐Ÿ“ฆย 47
Learning Resources ๐Ÿ“ฆย 147
Legal ๐Ÿ“ฆย 28
Libraries ๐Ÿ“ฆย 119
Lists Of Projects ๐Ÿ“ฆย 21
Machine Learning ๐Ÿ“ฆย 336
Mapping ๐Ÿ“ฆย 61
Marketing ๐Ÿ“ฆย 15
Mathematics ๐Ÿ“ฆย 55
Media ๐Ÿ“ฆย 228
Messaging ๐Ÿ“ฆย 97
Networking ๐Ÿ“ฆย 304
Operating Systems ๐Ÿ“ฆย 84
Operations ๐Ÿ“ฆย 120
Package Managers ๐Ÿ“ฆย 52
Programming Languages ๐Ÿ“ฆย 229
Runtime Environments ๐Ÿ“ฆย 96
Science ๐Ÿ“ฆย 42
Security ๐Ÿ“ฆย 375
Social Media ๐Ÿ“ฆย 26
Software Architecture ๐Ÿ“ฆย 70
Software Development ๐Ÿ“ฆย 68
Software Performance ๐Ÿ“ฆย 57
Software Quality ๐Ÿ“ฆย 127
Text Editors ๐Ÿ“ฆย 45
Text Processing ๐Ÿ“ฆย 131
User Interface ๐Ÿ“ฆย 310
User Interface Components ๐Ÿ“ฆย 465
Version Control ๐Ÿ“ฆย 29
Virtualization ๐Ÿ“ฆย 68
Web Browsers ๐Ÿ“ฆย 38
Web Servers ๐Ÿ“ฆย 25
Web User Interface ๐Ÿ“ฆย 194