Getting Started #

Overview #

Wite is a build tool that aims to provide a faster and leaner development experience for modern web projects. It consists of two major parts:

• A dev server that provides rich feature enhancements over native ES modules, for example extremely fast Hot Module Replacement (HMR).

• A build command that bundles your code with Rollup, pre-configured to output highly optimized static assets for production.

Wite is opinionated and comes with sensible defaults out of the box, but is also highly extensible via its Plugin API and JavaScript API with full typing support.

You can learn more about the rationale behind the project in the Why Wite section.

Browser Support #

The default build targets browsers that support both native ES Modules and native ESM dynamic import. Legacy browsers can be supported via the official @witejs/plugin-legacy - see the Building for Production section for more details.

Scaffolding Your First Wite Project #

With NPM:

$ npm create wite@latest

With Yarn:

$ yarn create wite

With PNPM:

$ pnpm create wite

Then follow the prompts!

You can also directly specify the project name and the template you want to use via additional command line options. For example, to scaffold a Wite + Kdu project, run:

# npm 6.x
npm create wite@latest my-kdu-app --template kdu

# npm 7+, extra double-dash is needed:
npm create wite@latest my-kdu-app -- --template kdu

# yarn
yarn create wite my-kdu-app --template kdu

# pnpm
pnpm create wite my-kdu-app --template kdu

See create-wite for more details on each supported template: vanilla, vanilla-ts, kdu, kdu-ts, react, react-ts, lit, lit-ts.

Community Templates #

create-wite is a tool to quickly start a project from a basic template for popular frameworks. You can use a tool like degit to scaffold your project with one of the templates.

npx degit user/project my-project
cd my-project

npm install
npm run dev

If the project uses main as the default branch, suffix the project repo with #main

npx degit user/project#main my-project

index.html and Project Root #

One thing you may have noticed is that in a Wite project, index.html is front-and-central instead of being tucked away inside public. This is intentional: during development Wite is a server, and index.html is the entry point to your application.

Wite treats index.html as source code and part of the module graph. It resolves <script type="module" src="..."> that references your JavaScript source code. Even inline <script type="module"> and CSS referenced via <link href> also enjoy Wite-specific features. In addition, URLs inside index.html are automatically rebased so there's no need for special %PUBLIC_URL% placeholders.

Similar to static http servers, Wite has the concept of a "root directory" which your files are served from. You will see it referenced as <root> throughout the rest of the docs. Absolute URLs in your source code will be resolved using the project root as base, so you can write code as if you are working with a normal static file server (except way more powerful!). Wite is also capable of handling dependencies that resolve to out-of-root file system locations, which makes it usable even in a monorepo-based setup.

Wite also supports multi-page apps with multiple .html entry points.

Specifying Alternative Root #

Running wite starts the dev server using the current working directory as root. You can specify an alternative root with wite serve some/sub/dir.

Command Line Interface #

In a project where Wite is installed, you can use the wite binary in your npm scripts, or run it directly with npx wite. Here are the default npm scripts in a scaffolded Wite project:

{
  "scripts": {
    "dev": "wite", // start dev server, aliases: `wite dev`, `wite serve`
    "build": "wite build", // build for production
    "preview": "wite preview" // locally preview production build
  }
}

You can specify additional CLI options like --port or --https. For a full list of CLI options, run npx wite --help in your project.

Community #

If you have questions or need help, reach out to the community at GitHub Discussions.