Preact

Common errors

• ReferenceError: h is not defined

  cause JSX factory function (`h`) is not configured for your build process (Babel/TypeScript).
  fix Configure your `tsconfig.json` (`jsxFactory: "h"`) or Babel config (`@babel/plugin-transform-react-jsx` with `pragma: 'h'`) to use Preact's `h` function for JSX, or add `/** @jsx h */` to your files.

• Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a CommonJS context (e.g., an older Node.js environment or a non-bundled script without proper module configuration).
  fix Ensure your project's `package.json` has `"type": "module"` for Node.js environments, or use a bundler (Webpack, Rollup, Vite) that handles ES module compilation for browser code.

• React is not defined

  cause A React-dependent library or component is being used in a Preact project without `preact/compat` being properly aliased to `react` and `react-dom` in the build configuration.
  fix Install `preact/compat` and configure your bundler (e.g., Webpack, Rollup) to alias `react` and `react-dom` imports to `preact/compat`.

• Hooks can only be called inside the body of a function component.

  cause A Preact hook (e.g., `useState`, `useEffect`) is being called outside of a functional component or a custom hook, violating the Rules of Hooks.
  fix Ensure all hook calls are made directly within the top level of a functional component or a custom hook, and not inside loops, conditions, or nested functions.

Warnings

• breaking For extensive compatibility with the broader React ecosystem (e.g., UI libraries, router components), installing `preact/compat` and aliasing `react` and `react-dom` to `preact/compat` in your bundler configuration (e.g., Webpack, Rollup) is critical. Failing to do so will result in runtime errors when using React-dependent libraries.
  Fix: Install `preact/compat` and configure your bundler to alias `react` and `react-dom` to `preact/compat`. Example for Webpack: `resolve.alias: { 'react': 'preact/compat', 'react-dom/test-utils': 'preact/compat/test-utils', 'react-dom': 'preact/compat' }`
• gotcha Preact uses `h` (or `jsx` for modern JSX transform) as its JSX factory function. You must configure your build tools (Babel, TypeScript) to use this function when compiling JSX, otherwise you will encounter `ReferenceError: h is not defined` or similar errors.
  Fix: For TypeScript, add `"jsxFactory": "h"` to `compilerOptions` in `tsconfig.json`. For Babel, configure `@babel/plugin-transform-react-jsx` with `"pragma": "h"`. Alternatively, add `/** @jsx h */` at the top of each JSX/TSX file.
• breaking Modern Preact versions, especially since v10, are primarily designed for ES Modules. Attempting to use `require('preact')` in a pure CommonJS environment without proper transpilation or module resolution can lead to errors like `Cannot use import statement outside a module` or unexpected behavior. Use a bundler or ensure your Node.js environment is configured for ESM.
  Fix: Ensure your project's `package.json` includes `"type": "module"` if running directly in Node.js, or use a bundler (Webpack, Rollup, Vite) that correctly transpiles and resolves ES Modules for browser environments. Always prefer `import` statements.
• breaking Preact version 11 is in beta (`11.0.0-beta.1`) and is expected to introduce breaking changes. While `10.x` is stable, users should anticipate a migration effort when upgrading to the next major release.
  Fix: Consult the official Preact v11 migration guide upon its stable release. Thoroughly test your application when upgrading from v10 to v11.

Install

• npm install preact npm
• yarn add preact yarn
• pnpm add preact pnpm

Imports

• h, render
  wrong:

  const { h, render } = require('preact');

  correct:

  import { h, render } from 'preact';

  `h` is the JSX factory function; `render` mounts Preact components to the DOM. Modern Preact primarily uses ES Modules.
• Component
  wrong:

  import Component from 'preact/Component';

  correct:

  import { Component } from 'preact';

  For class-based components, `Component` is imported directly from the `preact` package. Older setups might have used a separate path.
• useState, useEffect
  wrong:

  import { useState } from 'react';

  correct:

  import { useState, useEffect } from 'preact';

  Preact 10+ exports common hooks directly from the main `preact` package, mimicking React's hook API. Avoid accidentally importing from 'react'.
• Fragment
  wrong:

  import { Fragment } from 'react';

  correct:

  import { Fragment } from 'preact';

  Used for grouping multiple elements without adding an extra DOM node. Can be used with JSX `<Fragment>...</Fragment>` or `<>...</>` (if configured).

Quickstart

This quickstart demonstrates how to create and render a basic functional Preact component using JSX, including an initial mount and an in-place update to the DOM.

import { h, render } from 'preact';
// Configure JSX pragma for TypeScript or Babel via tsconfig.json or babel.config.js
// For TypeScript, add "jsxFactory": "h" to your compilerOptions.
// For Babel, configure @babel/plugin-transform-react-jsx with 'pragma': 'h'.
// Alternatively, add this pragma comment to the top of your JSX files:
/** @jsx h */

function Greeting({ name }) {
  return (
    <main>
      <h1>Hello, {name}!</h1>
      <p>This is a simple Preact application.</p>
      <button onClick={() => alert(`Welcome, ${name}!`)}>Say Hello</button>
    </main>
  );
}

// Initial render to the document body
render(
  <Greeting name="World" />,
  document.body
);

// Update the component in-place after 3 seconds
setTimeout(() => {
  render(
    <Greeting name="Preact User" />,
    document.body
  );
}, 3000);