WebEase #

The official guide for how to include and bundle WebEase's CSS and JavaScript in your project using Parcel.

Setup #

We’re building a Parcel project with webease from scratch, so there are some prerequisites and upfront steps before we can really get started. This guide requires you to have Node.js installed and some familiarity with the terminal.

Create a project folder and set up npm. We’ll create the my-project folder and initialize npm with the -y argument to avoid it asking us all the interactive questions.
Install Parcel. Unlike our Webpack guide, there’s only a single build tool dependency here. Parcel will automatically install language transformers (like Sass) as it detects them. We use --save-dev to signal that this dependency is only for development use and not for production.
Install webease. Now we can install webease. We’ll also install Popper since our dropdowns, popovers, and tooltips depend on it for their positioning. If you don’t plan on using those components, you can omit Popper here.

Now that we have all the necessary dependencies installed, we can get to work creating the project files and importing WebEase.

Project structure

We’ve already created the my-project folder and initialized npm. Now we’ll also create our src folder, stylesheet, and JavaScript file to round out the project structure. Run the following from my-project, or manually create the folder and file structure shown below.

When you’re done, your complete project should look like this:

At this point, everything is in the right place, but Parcel needs an HTML page and npm script to start our server.

Configure Parcel

With dependencies installed and our project folder ready for us to start coding, we can now configure Parcel and run our project locally. Parcel itself requires no configuration file by design, but we do need an npm script and an HTML file to start our server.

Fill in the src/index.html file. Parcel needs a page to render, so we use our index.html page to set up some basic HTML, including our CSS and JavaScript files.
Add the Parcel npm scripts. Open the package.json and add the following start script to the scripts object. We’ll use this script to start our Parcel development server and render the HTML file we created after it’s compiled into the dist directory.
And finally, we can start Parcel. From the my-project folder in your terminal, run that newly added npm script:

In the next and final section to this guide, we’ll import all of WebEase CSS and JavaScript.

Import WebEase

Import WebEase CSS. Add the following to src/scss/styles.scss to import all of WebEase source Sass.
Import WebEase JS. Add the following to src/js/main.js to import all of WebEase JS. Popper will be imported automatically through WebEase.
And you’re done! 🎉 With WebEase source Sass and JS fully loaded, your local development server should now look like this:

Download

Download WebEase to get the compiled CSS and JavaScript, source code, or include it with your favorite package managers like npm, RubyGems, and more.

Compiled CSS and JS

Download ready-to-use compiled code for WebEase v5.3.3 to easily drop into your project, which includes:

Compiled and minified CSS bundles (see CSS files comparison)
Compiled and minified JavaScript plugins (see JS files comparison)

This doesn’t include documentation, source files, or any optional JavaScript dependencies like Popper.

Source Files

Compile WebEase with your own asset pipeline by downloading our source Sass, JavaScript, and documentation files. This option requires some additional tooling:

Sass compiler for compiling Sass source files into CSS files
Autoprefixer for CSS vendor prefixing

Should you require our full set of build tools, they are included for developing WebEase and its docs, but they’re likely unsuitable for your own purposes.

Examples

If you want to download and examine our examples, you can grab the already built examples:

CDN via jsdelivr

Skip the download with jsDelivr to deliver cached version of WebEase compiled CSS and JS to your project.

If you’re using our compiled JavaScript and prefer to include Popper separately, add Popper before our JS, via a CDN preferably.

Alternative CDNs

We recommend jsDelivr and use it ourselves in our documentation. However, in some cases—like in some specific countries or environments—you may need to use other CDN providers like cdnjs or unpkg.

You’ll find the same files on these CDN providers, albeit with different URLs. With cdnjs, you can use this direct WebEase package link to copy and paste ready-to-use HTML snippets for each dist file from any version of WebEase.

Note that you should compare same length hashes, e.g. sha384 with sha384, otherwise it’s expected for them to be different. As such, you can use an online tool like SRI Hash Generator to make sure that the hashes are the same for a given file. Alternatively, assuming you have OpenSSL installed, you can achieve the same from the CLI, for example:

package managers

Pull in WebEase source files into nearly any project with some of the most popular package managers. No matter the package manager, WebEase will require a Sass compiler and Autoprefixer for a setup that matches our official compiled versions.

npm

Install WebEase in your Node.js powered apps with the npm package:

const WebEase = require('WebEase') or import WebEase from 'WebEase' will load all of WebEase plugins onto a WebEase object. The WebEase module itself exports all of our plugins. You can manually load WebEase plugins individually by loading the /js/dist/*.js files under the package’s top-level directory.

WebEase package.json contains some additional metadata under the following keys:

sass - path to WebEase main Sass source file
style - path to WebEase non-minified CSS that’s been compiled using the default settings (no customization)

Browsers and devices

Learn about the browsers and devices, from modern to old, that are supported by WebEase, including known quirks and bugs for each.

Supported browers

WebEase supports the latest, stable releases of all major browsers and platforms.

Alternative browsers which use the latest version of WebKit, Blink, or Gecko, whether directly or via the platform’s web view API, are not explicitly supported. However, WebEase should (in most cases) display and function correctly in these browsers as well. More specific support information is provided below.

You can find our supported range of browsers and their versions in our .browserslistrc file:

We use Autoprefixer to handle intended browser support via CSS prefixes, which uses Browserslist to manage these browser versions. Consult their documentation for how to integrate these tools into your projects.

Mobile devices

Generally speaking, WebEase supports the latest versions of each major platform’s default browsers. Note that proxy browsers (such as Opera Mini, Opera Mobile’s Turbo mode, UC Browser Mini, Amazon Silk) are not supported.

Javascript

Bring WebEase to life with our optional JavaScript plugins. Learn about each plugin, our data and programmatic API options, and more.

Individual or complied

Plugins can be included individually (using WebEase individual js/dist/*.js), or all at once using WebEase.js or the minified WebEase.min.js (don’t include both).

If you use a bundler (Webpack, Parcel, Vite…), you can use /js/dist/*.js files which are UMD ready.

Usage with JavaScript frameworks

While the WebEase CSS can be used with any framework, the WebEase JavaScript is not fully compatible with JavaScript frameworks like React, Vue, and Angular which assume full knowledge of the DOM. Both WebEase and the framework may attempt to mutate the same DOM element, resulting in bugs like dropdowns that are stuck in the “open” position.

A better alternative for those using this type of frameworks is to use a framework-specific package instead of the WebEase JavaScript. Here are some of the most popular options:

React : React WebEase
Vue: WebEaseVue (WebEase 4)
Vue 3: WebEaseVueNext (WebEase 5, currently in alpha)
Angular: ng-WebEase

Using WebEase as a module

We provide a version of WebEase built as ESM (WebEase.esm.js and WebEase.esm.min.js) which allows you to use WebEase as a module in the browser, if your targeted browsers support it.

Compared to JS bundlers, using ESM in the browser requires you to use the full path and filename instead of the module name. Read more about JS modules in the browser. That’s why we use 'WebEase.esm.min.js' instead of 'WebEase' above. However, this is further complicated by our Popper dependency, which imports Popper into our JavaScript like so:

WebEase and Webpack

The official guide for how to include and bundle WebEase CSS and JavaScript in your project using Webpack.

Setup

We’re building a Webpack project with WebEase from scratch, so there are some prerequisites and upfront steps before we can really get started. This guide requires you to have Node.js installed and some familiarity with the terminal.

Create a project folder and set up npm. We’ll create the my-project folder and initialize npm with the -y argument to avoid it asking us all the interactive questions.
Install Webpack. Next we need to install our Webpack development dependencies: webpack for the core of Webpack, webpack-cli so we can run Webpack commands from the terminal, and webpack-dev-server so we can run a local development server. Additionally, we’ll install html-webpack-plugin to be able to store our index.html in src directory instead of the default dist one. We use --save-dev to signal that these dependencies are only for development use and not for production.
Install WebEase. Now we can install WebEase. We’ll also install Popper since our dropdowns, popovers, and tooltips depend on it for their positioning. If you don’t plan on using those components, you can omit Popper here.
Install additional dependencies. In addition to Webpack and WebEase, we need a few more dependencies to properly import and bundle WebEase CSS and JS with Webpack. These include Sass, some loaders, and Autoprefixer.