Support Us

Getting Started

New to Preact? New to Virtual DOM? Check out the tutorial.

This guide helps you get up and running to start developing Preact apps, using 3 popular options. If you're new to Preact, we recommend starting with Vite.

No build tools route

Preact is packaged to be used directly in the browser, and doesn't require any build or tools:

<script type="module">
  import { h, Component, render } from '';

  // Create your app
  const app = h('h1', null, 'Hello World!');

  render(app, document.body);

🔨 Edit on Glitch

The primary drawback of developing this way is the lack of JSX, which requires a build step. An ergonomic and performant alternative to JSX is documented in the next section.

Alternatives to JSX

Writing raw h or createElement calls can be tedious. JSX has the advantage of looking similar to HTML, which makes it easier to understand for many developers in our experience. JSX requires a build step though, so we highly recommend an alternative called HTM.

HTM is a JSX-like syntax that works in standard JavaScript. Instead of requiring a build step, it uses JavaScript's own Tagged Templates syntax, which was added in 2015 and is supported in all modern browsers. This is an increasingly popular way to write Preact apps, since there are fewer moving parts to understand than a traditional front-end build tooling setup.

<script type="module">
  import { h, Component, render } from '';
  import htm from '';

  // Initialize htm with Preact
  const html = htm.bind(h);

  function App (props) {
    return html`<h1>Hello ${}!</h1>`;

  render(html`<${App} name="World" />`, document.body);

🔨 Edit on Glitch

Tip: HTM also provides a convenient single-import Preact version:

import { html, render } from ''

For more information on HTM, check out its documentation.

Create a Vite-Powered Preact App

Vite has become an incredibly popular tool for building applications across many frameworks in the past couple of years, and Preact is no exception. It's built upon popular tooling like ES modules, Rollup, and ESBuild. Vite, through our initializer or their Preact template, requires no configuration or prior knowledge to get started and this simplicity makes it a very popular way to use Preact.

To get up and running with Vite quickly, you can use our initializer create-preact. This is an interactive command-line interface (CLI) app that can be run in the terminal on your machine. Using it, you can create a new application by running the following:

npm init preact

This will walk you through creating a new Preact app and gives you some options such as TypeScript, routing (via preact-iso), and ESLint support.

Tip: None of these decisions need to be final, you can always add or remove them from your project later if you change your mind.

Getting ready for development

Now we're ready to start our application. To start a development server, run the following command inside your newly generated project folder:

# Go into the generated project folder
cd my-preact-app

# Start a development server
npm run dev

Once the server has started, it will print a local development URL to open in your browser. Now you're ready to start coding your app!

Making a production build

There comes a time when you need to deploy your app somewhere. Vite ships with a handy build command which will generate a highly-optimized production build.

npm run build

Upon completion, you'll have a new dist/ folder which can be deployed directly to a server.

For a full list of all available commands and their options, check out the Vite CLI Documentation.

Integrating Into An Existing Pipeline

If you already have an existing tooling pipeline set up, it's very likely that this includes a bundler. The most popular choices are webpack, rollup or parcel. Preact works out of the box with all of them. No changes needed!

Setting up JSX

To transpile JSX, you need a Babel plugin that converts it to valid JavaScript code. The one we all use is @babel/plugin-transform-react-jsx. Once installed, you need to specify the function for JSX that should be used:

  "plugins": [
    ["@babel/plugin-transform-react-jsx", {
      "pragma": "h",
      "pragmaFrag": "Fragment",

Babel has some of the best documentation out there. We highly recommend checking it out for questions surrounding Babel and how to set it up.

Aliasing React to Preact

At some point, you'll probably want to make use of the vast React ecosystem. Libraries and Components originally written for React work seamlessly with our compatibility layer. To make use of it, we need to point all react and react-dom imports to Preact. This step is called aliasing.

Note: If you're using Vite, Preact CLI, or WMR, these aliases are automatically handled for you by default.

Aliasing in webpack

To alias any package in webpack, you need to add the resolve.alias section to your config. Depending on the configuration you're using, this section may already be present, but missing the aliases for Preact.

const config = {
  "resolve": {
    "alias": {
      "react": "preact/compat",
      "react-dom/test-utils": "preact/test-utils",
      "react-dom": "preact/compat",     // Must be below test-utils
      "react/jsx-runtime": "preact/jsx-runtime"

Aliasing in Node

When we are on a Node.JS server our webpack aliases won't work, this is seen in Next/... here we will have to use an alias in our package.json.

  "dependencies": {
    "react": "npm:@preact/compat",
    "react-dom": "npm:@preact/compat",

Now Node will correctly use Preact in place of React.

Aliasing in Parcel

Parcel uses the standard package.json file to read configuration options under an alias key.

  "alias": {
    "react": "preact/compat",
    "react-dom/test-utils": "preact/test-utils",
    "react-dom": "preact/compat",
    "react/jsx-runtime": "preact/jsx-runtime"

Aliasing in Rollup

To alias within Rollup, you'll need to install @rollup/plugin-alias. The plugin will need to be placed before your @rollup/plugin-node-resolve

import alias from '@rollup/plugin-alias';

module.exports = {
  plugins: [
      entries: [
        { find: 'react', replacement: 'preact/compat' },
        { find: 'react-dom/test-utils', replacement: 'preact/test-utils' },
        { find: 'react-dom', replacement: 'preact/compat' },
        { find: 'react/jsx-runtime', replacement: 'preact/jsx-runtime' }

Aliasing in Jest

Jest allows the rewriting of module paths similar to bundlers. These rewrites are configured using regular expressions in your Jest configuration:

  "moduleNameMapper": {
    "^react$": "preact/compat",
    "^react-dom/test-utils$": "preact/test-utils",
    "^react-dom$": "preact/compat",
    "^react/jsx-runtime$": "preact/jsx-runtime"

Aliasing in Snowpack

To alias in Snowpack, you'll need to add a package import alias to the snowpack.config.mjs file.

// snowpack.config.mjs
export default {
  alias: {
    "react": "preact/compat",
    "react-dom/test-utils": "preact/test-utils",
    "react-dom": "preact/compat",
    "react/jsx-runtime": "preact/jsx-runtime",

TypeScript preact/compat configuration

Your project could need support for the wider React ecosystem. To make your application compile, you might need to disable type checking on your node_modules and add paths to the types like this. This way, your alias will work properly when libraries import React.

  "compilerOptions": {
    "skipLibCheck": true,
    "baseUrl": "./",
    "paths": {
      "react": ["./node_modules/preact/compat/"],
      "react-dom": ["./node_modules/preact/compat/"]

Built by a bunch of lovely people.