Preact Deployment and Usage Guide

Prerequisites

• Node.js (version 12.0.0 or higher)
• npm (version 6.0.0 or higher)
• Git for version control
• Modern web browser (Chrome, Firefox, Safari, or Edge) for development

Installation

Clone the Repository

git clone https://github.com/preactjs/preact.git
cd preact

Install Dependencies

npm install

Build the Project

npm run build

This will compile the source code and generate the production-ready files in the dist directory.

Configuration

Preact doesn't require extensive configuration for basic usage. However, you may need to configure your build tools:

Babel Configuration

For JSX support, configure Babel with the following plugin:

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

TypeScript Configuration

For TypeScript projects, configure the JSX factory:

{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "h",
    "jsxFragmentFactory": "Fragment"
  }
}

Environment Variables

Preact doesn't require specific environment variables for core functionality. However, if you're using Preact with other services, you may need to set:

• NODE_ENV - Set to development or production
• Custom API keys for your application services

Build & Run

Development Server

npm run dev

This starts a development server with hot module replacement (HMR) enabled. The server typically runs on http://localhost:8080.

Production Build

npm run build

This creates an optimized production build in the dist directory.

Running Tests

npm test

This runs the test suite to verify your changes.

Deployment

Preact applications can be deployed to various platforms. Here are some recommended options:

Static Hosting (Vercel, Netlify, GitHub Pages)

For static sites built with Preact:

# Build for production
npm run build

# Deploy the dist directory
# For Vercel: Connect your repository and deploy
# For Netlify: Drag and drop the dist folder or connect your repo
# For GitHub Pages: Use the gh-pages npm package

Node.js Server (Vercel, Railway, Heroku)

For server-side rendering with Preact:

# Build the application
npm run build

# Start the server
npm start

Deploy the entire project to platforms that support Node.js.

Docker Deployment

Create a Dockerfile:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

RUN npm run build

EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t my-preact-app .
docker run -p 3000:3000 my-preact-app

Troubleshooting

Common Issues and Solutions

1. JSX Not Compiling

Issue: JSX syntax not being transformed correctly.

Solution: Ensure your build tool (Babel, TypeScript) is configured with the correct JSX pragma:

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

2. Component Not Rendering

Issue: Components not appearing in the DOM.

Solution: Verify you're using the correct import:

import { h, render } from 'preact';

3. Prop Type Warnings

Issue: PropTypes warnings in development.

Solution: Use the prop-types package or TypeScript for type checking:

npm install prop-types

4. Hydration Mismatch

Issue: Server-side rendering hydration errors.

Solution: Ensure your server and client render the same content:

import { hydrate } from 'preact';
import App from './App';

hydrate(<App />, document.getElementById('root'));

5. Performance Issues

Issue: Application running slowly.

Solution: Use production builds and consider code splitting:

import { lazy, Suspense } from 'preact/compat';

const LazyComponent = lazy(() => import('./LazyComponent'));

6. Compatibility Issues

Issue: React libraries not working with Preact.

Solution: Use the preact/compat alias for React compatibility:

import React from 'preact/compat';

7. Hook Rules Violation

Issue: React Hook rules not being followed.

Solution: Ensure hooks are called at the top level of your components:

function Component() {
  const [state, setState] = useState(null);
  // Correct: hooks at top level
  return <div />;
}

Getting Help

• Documentation: Visit preactjs.com for comprehensive guides
• Community: Join the Preact Slack Community
• Issues: Report bugs on the GitHub repository
• Discussions: Ask questions on the GitHub Discussions