@evolvedweb/wc

Create blazing fast, lightweight, native, custom elements,
with minimal boilerplate and
almost no runtime libraries.

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. Contributing
5. Roadmap
6. License
7. Contact

About The Evo-wc 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 transpiles 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 JSDOC Types.

Dependencies

1. Build-time dependencies for Evo-wc:
   • fast-xml-parser
   • glob
   • html-minifier-terser
2. Node runtime dependencies that are only for running the demo server:
   • express
   • keypress
   • micromatch
   • node-watch
3. Developer dependencies for developing and testing Evo-wc are:
   • @types/mocha
   • @types/node
   • c8
   • chai
   • eslint
   • esmock
   • mocha
   • nock

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 Evo-wc in your project
   npm install @evolvedweb/wc

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

   # Initialize Evo-wc 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

Creating Evo templates is straightforward. For the best compatibility and ease of use, it's advised to use HTML files for your component templates. Most code editors provide better support for HTML compared to XML.

Here’s a step-by-step guide to creating a new component in Evo:

1. Create a Template File: Begin by adding a new HTML file in the components folder for your new component.

2. Transpile the Template: Run the command npm run evowc in your terminal. This process transpiles all your template files into JavaScript files, each representing a custom element.

3. Import Custom Elements: In your main HTML file, use the import statement to include the JavaScript files of your custom elements. This step is crucial for integrating the components into your application.

4. Add Element Tags: Place the tags of your custom elements in the HTML file where you want these components to appear.

And that's pretty much it! The only additional steps involve specific functionalities or features you want to embed within your components. This simple workflow highlights the ease and efficiency of using Evo for web development.

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)

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)

Roadmap

This section will only show the current released version and anything planned for the future. Review the UPDATELOG.md for past changes

• ☑ Get all Issues related to 1.1.3 finished:
  • ☑ #96 - Updated dependencies.
  • ☑ #97 - Init and transpiler work correctly on Windows.
  • ☑ #98 - Exception in WCAElement.
  • ☑ #99 - Exception in WCRouterElement.
  • ☑ #100 - CSS loading error HighlightCodeElement.
  • ☑ Repo Updates.
  • ☑ Bug fixes.
• ☑ Release version 1.1.3.
• ☐ Get all Issues related to 1.1.4 finished:
  • ☐ #88 - Add new Evo pipe: sanitize.
  • ☐ #95 - Fix Update to copy over used components like WCAElement.html bug.
• ☐ Release version 1.1.4.
• ☐ Get all Issues related to 1.2.0 finished:
  • ☐ #85 - Increase Unit tests to over 85% coverage bug.
  • ☐ #89 - Support basic interpolation inside a tag.
  • ☐ #90 - Support basic interpolation in an attribute.
• ☐ Release version 1.2.0.
• ☐ Get all Issues related to 1.2.1 finished:
  • ☐ #91 - Support basic expressions in an event handler.
  • ☐ #93 - Support basic expressions in $if, $switch and interpolation rendering.
• ☐ Release version 1.2.1.
• ☐ Get all Issues related to 2.0.0 finished:
  • ☐ #21 - Add unit testing for all files that are part of the transpiler.
  • ☐ #29 - Fix browser refresh to load updated transpiled component files.
  • ☐ #41 - Need to support this.attachInternals().
  • ☐ #50 - Support form-associated custom elements.
  • ☐ #81 - Add new Evo pipe: toRelTime.
  • ☐ #83 - Finish EvoState for Evo components.
  • ☐ #85 - Unit testing over 85% coverage.
  • ☐ Create simple React app with Evo integration points.
  • ☐ Functional Tests for main components.
  • ☐ Repo Updates.
  • ☐ Bug fixes.
• ☐ Release version 2.0.0.
• ☐ Issues related to any future version:
  • ☐ #22 - Add VSCode plugin to improve support of the template files.
  • ☐ #35 - Investigate code during transpile and remove unused or not-required generated code. (See #72)
  • ☐ #37 - Protect the init and update functions. Making the private, if possible.
  • ☐ #46 - Create a way to list all of the Components available in the repo.
  • ☐ #47 - Add ability to auto generate mapping files
  • ☐ #51 - Support Scoped Styles: the @scope rule for non-shadow-dom elements.
  • ☐ #54 - Support fragments inside the template.
  • ☐ #56 - Add auto-browser refresh when any component file auto-rebuilds.
  • ☐ #58 - Add acceptance tests for Evowc and a simple way for all project made using Evowc.
  • ☐ #72 - Integrate AST for compile time error checking and validation (See #35)
  • ☐ #76 - Add support for adoptedStyleSheets
  • ☐ #82 - Add error message output as component for transpile errors so they are visible.
  • ☐ #84 - Add hooks for router (BeforeUnload, BeforeLoad, AfterLoad, Guard, and possibly others).
  • ☐ #86 - Look at path-to-regexp project to replace our internal code.
  • ☐ #91 - Support basic expressions in an event handler enhancement
  • ☐ #93 - Support basic expressions in $if, $switch and interpolation rendering enhancement
  • ☐ Add EvoState support for React.
  • ☐ Add EvoState support for Angular.
  • ☐ Finish online editor/tester.
  • ☐ Support generating Server Side versions for Server Side Rendering and Hydration.
  • ☐ Add code to generate server RPC code and calls from client.
    • ☐ Node, Deno, .NET, PHP, Python, Rust, Java, others
  • ☐ Repo Updates.
  • ☐ Bug fixes.
• ☐ Release version

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

(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)