@evolvedweb/wc

Create lightweight, high-performance native custom elements, with minimal boilerplate.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

Evo-wc, or Evolved Web Components, is a Web Component transpiler. The developer builds simple XML files that are very similar to and HTML with only the code they need. Evo-wc trnaspiles the XMl files into a JavaScript file that contains a native Custom Element.

Evo-wc offers developers a powerful and efficient way to create web components, whether used independently or alongside existing frameworks. The generated elements are standards based and run lightning fast. Here are several compelling reasons why someone would want to consider using Evo:

1. Reduced Boilerplate Code: Evo dramatically reduces the amount of boilerplate code needed to create web components. Traditional web component development often involves writing extensive code for property accessors, event handling, and templating. Evo simplifies this process, allowing developers to focus on the core functionality of their components. This efficiency can save a significant amount of development time.

2. Native Web Components: Evo leverages the native web component standard, which has gained widespread browser support. This means that Evo-generated components can seamlessly integrate into web applications without relying on additional libraries or frameworks. Developers can enjoy the benefits of web components' encapsulation and reusability without the complexity of custom solutions.

3. Minimal Runtime Overhead: One of Evo's key strengths is its ability to shift much of the work from runtime to build time. This results in minimal runtime overhead, ensuring that Evo-generated components are highly performant. Faster-loading components lead to a more responsive user experience, making Evo an excellent choice for optimizing web applications.

4. Versatility with Existing Frameworks: Evo is not limited to standalone use. Developers can incorporate Evo-generated components into existing web frameworks, such as React, Angular, or Vue.js. This versatility allows for gradual adoption, enabling teams to leverage Evo's benefits in specific areas of their application while maintaining compatibility with their chosen framework.

5. Data Binding and Event Handling: Evo simplifies data binding and event handling within components. With straightforward syntax, developers can bind component properties to elements in the template, facilitating real-time updates. Event handling is equally intuitive, using native DOM events. This streamlines communication between components and ensures seamless interactivity.

6. Conditional Rendering and Looping: Evo introduces conditional directives like $if and $switch for flexible and efficient conditional rendering. It also supports looping through data arrays with the $for directive. These features empower developers to create dynamic user interfaces with ease.

7. Community and Ongoing Development: Evo has a growing community of developers and contributors who actively support its development. Regular updates and improvements ensure that Evo remains aligned with evolving web standards and best practices.

In summary, Evo provides a developer-friendly, high-performance solution for creating web components. Whether used independently to harness the full power of native web components or integrated into existing frameworks for enhanced flexibility, Evo simplifies the development process and contributes to the creation of efficient and maintainable web applications.

(back to top)

Built With

Built in Raw JavaScript using JSDocs Types.

Our build-time dependencies are:

• fast-xml-parser
• glob
• html-minifier-terser

The runtime dependencies for running the demo server:

• express
• keypress
• micromatch
• node-watch

The developer dependencies for testing Evowc are:

• chai
• eslint
• mocha
• nyc
• proxyquire
• sinon

None of these dependencies are used at runtime by the generated components. The only code executed at runtime consists of your transpiled components and a base class that encapsulates all the common functionality shared by all of the components. Additionally, there are optional files available specifically for the Evo router.

(back to top)

Getting Started

Prerequisites

To use Evo-wc you will need NodeJs installed. We recommend LTS and have tested with versions between 18 and 20.

Installation

To install and test Evo follow the steps below. Evo init will create a demo server that works well for development but is not recommended for use in production. It also creates a simple website that uses a series of demo web components and the built in <wc-router> element for SPA styled routing and the <wc-a> to navigate between the SPA pages.

1. Install Nodejs if needed
   Download and install from https://nodejs.org/.

   There are many good sites that describe the process in details. Look here for more details.

2. Create a Project Folder:
   Create a new folder for your Evo project and change directory into it. This will be the root directory for your web components. Open your terminal application and enter the following commands:

   # Create the new folder
   mkdir evo1
   
   # Go into the newly created folder
   cd evo1
   

3. Install Evo:
   Begin by initializing npm and then installing Evo. In your terminal run the following commands:

   # Initialize the npm project
   npm init
   
   # Press enter multiple times until the init has finished
   
   # install EvoWC in your project
   npm install @evolvedweb/wc
   

4. Initialize Evo:
   Let Evo know ceate a demo server and where your component template and the transpiled components will be placed.

   # Initialize EVOWC config and copy the helper files
   npx evowc init
   
   # Install the added repos for the demo server
   npm i
   
   # Transpile the demo Evo components and start the demo server
   npm run watch
   

5. Browser to the demo server at http://localhost:12345

(back to top)

Usage

Evo template files are easy to create. It is recommended that you create HTML files for your code because editors handle them better than XML files.

To create a new component you add a new template file into the components folder and then run npm evowc to transpile all of the template files.

Include the generated JavaScript file into your HTML file and add your tag into the HTML. That is it. Anything else you add will be based on the needs of your components.

You can learn more on the Getting Started page or the Examples page.

You can read more about how to use Evo in the Documentation. Or review the Frequently Asked Questions.

(back to top)

Roadmap

• ☑ Release version 0.5.0
• ☑ Fix errors and enhancements for v0.6.0
  • ☑ Improve documentation.
• ☑ Release version 0.6.0
• ☑ Fix errors and enhancements for v0.7.0
  • ☑ Increase unit tests to over 40%
  • ☑ Add hot-transpile. Components will auto-transpile when changed in the Evo demo app.
  • ☑ Improve demo website.
    • ☑ Use the Evo router.
    • ☑ Add a couple demo pages.
    • ☑ Include several of the example components.
• ☑ Release version 0.7.0
• ☑ Fix all errors and enhancements for version 1.0.0
  • ☑ All docs up to date.
  • ☑ Unit tests over 60%.
• ☑ Release version 1.0.0
• ☐ Get all Issues related to 2.0.0 finished
  • ☐ callbacks for onUpdate should be passed the current path
  • ☐ Upgrade the router onUpdate to take a startsWith string
  • ☐ Add auto-browser refresh when any component file auto-rebuilds
  • ☐ Consider how to support fragments inside the template
  • ☐ Support external JS files for the <script> tag
  • ☐ Support external CSS files
  • ☐ Support Scoped Styles: the @scope rule for non-shadow-dom elements
  • ☐ Support form-associated custom elements
  • ☐ Work with html-minifier-terser to define custom pre-formatted tags
  • ☐ Need to support this.attachInternals()
  • ☐ Fix browser refresh to load updated transpiled component files.
  • ☐ Create a new logo
  • ☐ Add onUpdate function to allow for monitoring specific property changes
  • ☐ Add unit testing for all files that are part of the transpiler
  • ☐ Add event binding to the <template> tag
  • ☐ Event Handlers - Support Capture, Passive, Once
• ☐ Release version 2.0.0

See the open issues for the current list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request.

1. Fork the Project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Create you amazing feature
4. Add unit testing (90% or better coverage for the new code)
5. Commit your changes (git commit -m 'Add some AmazingFeature')
6. Push to the branch (git push origin feature/AmazingFeature)
7. Open a Pull Request

You can also open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Michael Collins:

• Linked In
• The Evo Slack Workspace

Project Links:

• https://github.com/EvolvedWeb/evowc
• Documentation
• Examples

(back to top)