0
# Preact
1
2
Preact is a fast, lightweight 3kB alternative to React that provides the same modern API and development experience. It offers a complete Virtual DOM implementation with familiar React patterns including ES6 classes, hooks, and functional components, while maintaining extensive React compatibility and superior performance.
3
4
## Package Information
5
6
- **Package Name**: preact
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install preact`
10
11
## Core Imports
12
13
```typescript
14
import { render, createElement, Component, Fragment } from "preact";
15
```
16
17
For React compatibility:
18
19
```typescript
20
import { render, Component, useState, useEffect } from "preact/compat";
21
```
22
23
For hooks:
24
25
```typescript
26
import { useState, useEffect, useMemo, useCallback } from "preact/hooks";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import { render, createElement, Component } from "preact";
33
34
// Functional component
35
function Hello({ name }: { name: string }) {
36
return createElement("h1", null, `Hello ${name}!`);
37
}
38
39
// Class component
40
class Counter extends Component<{}, { count: number }> {
41
state = { count: 0 };
42
43
increment = () => {
44
this.setState({ count: this.state.count + 1 });
45
};
46
47
render() {
48
return createElement("div", null,
49
createElement("p", null, `Count: ${this.state.count}`),
50
createElement("button", { onClick: this.increment }, "Increment")
51
);
52
}
53
}
54
55
// Render to DOM
56
render(createElement(Counter), document.getElementById("app"));
57
```
58
59
## Architecture
60
61
Preact is built around several key components:
62
63
- **Virtual DOM**: Lightweight virtual representation of the DOM with minimal overhead
64
- **Component System**: Both class-based and functional components with full lifecycle support
65
- **Hooks Integration**: Complete React hooks API through `preact/hooks` module
66
- **React Compatibility**: Drop-in React replacement through `preact/compat` module
67
- **Modular Design**: Core features split across specialized modules for optimal bundle size
68
- **TypeScript Support**: Full type definitions with excellent IntelliSense integration
69
70
## Capabilities
71
72
### Core Virtual DOM
73
74
Essential functions for creating and rendering virtual DOM elements. Provides the foundation for all Preact applications.
75
76
```typescript { .api }
77
function render(vnode: ComponentChild, parent: ContainerNode): void;
78
function createElement<P>(
79
type: ComponentType<P> | string,
80
props: P | null,
81
...children: ComponentChildren[]
82
): VNode<P>;
83
function Fragment(props: { children?: ComponentChildren }): ComponentChildren;
84
```
85
86
[Core Virtual DOM](./core.md)
87
88
### Component System
89
90
Class-based and functional component patterns with complete lifecycle methods and state management capabilities.
91
92
```typescript { .api }
93
abstract class Component<P = {}, S = {}> {
94
setState<K extends keyof S>(
95
state: Partial<S> | ((prevState: S, props: P) => Partial<S>),
96
callback?: () => void
97
): void;
98
forceUpdate(callback?: () => void): void;
99
abstract render(props?: P, state?: S, context?: any): ComponentChildren;
100
}
101
102
interface FunctionComponent<P = {}> {
103
(props: RenderableProps<P>, context?: any): ComponentChildren;
104
displayName?: string;
105
defaultProps?: Partial<P>;
106
}
107
```
108
109
[Component System](./components.md)
110
111
### Hooks API
112
113
Modern React hooks for state management, side effects, and component logic in functional components.
114
115
```typescript { .api }
116
function useState<S>(initialState?: S | (() => S)): [S, Dispatch<SetStateAction<S>>];
117
function useEffect(effect: EffectCallback, deps?: DependencyList): void;
118
function useMemo<T>(factory: () => T, deps: DependencyList): T;
119
function useCallback<T extends (...args: any[]) => any>(callback: T, deps: DependencyList): T;
120
```
121
122
[Hooks API](./hooks.md)
123
124
### React Compatibility
125
126
Complete React compatibility layer enabling seamless migration from React applications with advanced features like Suspense and portals.
127
128
```typescript { .api }
129
function memo<P>(
130
component: ComponentType<P>,
131
propsAreEqual?: (prevProps: P, nextProps: P) => boolean
132
): ComponentType<P>;
133
function forwardRef<T, P = {}>(
134
render: (props: P, ref: Ref<T>) => ComponentChildren
135
): ComponentType<P & RefAttributes<T>>;
136
function createPortal(children: ComponentChildren, container: Element): VNode;
137
```
138
139
[React Compatibility](./compat.md)
140
141
### Context API
142
143
Provider/consumer pattern for sharing data across component hierarchies without prop drilling.
144
145
```typescript { .api }
146
function createContext<T>(defaultValue: T): Context<T>;
147
148
interface Context<T> {
149
Provider: ComponentType<{ value: T; children?: ComponentChildren }>;
150
Consumer: ComponentType<{ children: (value: T) => ComponentChildren }>;
151
displayName?: string;
152
}
153
```
154
155
[Context API](./context.md)
156
157
### Development Tools
158
159
Development utilities, debugging helpers, and React DevTools integration for enhanced developer experience.
160
161
```typescript { .api }
162
function addHookName<T>(value: T, name: string): T;
163
function getCurrentVNode(): VNode | null;
164
function getDisplayName(vnode: VNode): string;
165
```
166
167
[Development Tools](./devtools.md)
168
169
### Testing Utilities
170
171
Testing helpers for managing component rendering, effects flushing, and test environment setup.
172
173
```typescript { .api }
174
function setupRerender(): () => void;
175
function act(callback: () => void | Promise<void>): Promise<void>;
176
function teardown(): void;
177
```
178
179
[Testing Utilities](./testing.md)
180
181
### JSX Runtime
182
183
Modern JSX transformation runtime for automatic JSX compilation and template-based JSX. Used by build tools for transforming JSX syntax.
184
185
```typescript { .api }
186
function jsx<P>(type: ComponentType<P> | string, props: P, key?: Key): VNode<P>;
187
function jsxs<P>(type: ComponentType<P> | string, props: P, key?: Key): VNode<P>;
188
function jsxDEV<P>(type: ComponentType<P> | string, props: P, key?: Key): VNode<P>;
189
function jsxTemplate(template: TemplateStringsArray, ...expressions: any[]): VNode | ComponentChildren;
190
```
191
192
[JSX Runtime](./jsx-runtime.md)
193
194
## Types
195
196
### Core Types
197
198
```typescript { .api }
199
type ComponentChild =
200
| VNode<any>
201
| object
202
| string
203
| number
204
| bigint
205
| boolean
206
| null
207
| undefined;
208
209
type ComponentChildren = ComponentChild[] | ComponentChild;
210
211
type Key = string | number | any;
212
213
interface VNode<P = {}> {
214
type: ComponentType<P> | string;
215
props: P & { children: ComponentChildren };
216
key: Key;
217
ref?: Ref<any> | null;
218
}
219
220
type Ref<T> = RefObject<T> | RefCallback<T> | null;
221
type RefObject<T> = { current: T | null };
222
type RefCallback<T> = (instance: T | null) => void | (() => void);
223
224
type RenderableProps<P, RefType = any> = P &
225
Readonly<Attributes & { children?: ComponentChildren; ref?: Ref<RefType> }>;
226
227
interface Attributes {
228
key?: Key | undefined;
229
jsx?: boolean | undefined;
230
}
231
232
interface ClassAttributes<T> extends Attributes {
233
ref?: Ref<T>;
234
}
235
```
236
237
### Component Types
238
239
```typescript { .api }
240
type ComponentType<P = {}> = ComponentClass<P> | FunctionComponent<P>;
241
242
interface ComponentClass<P = {}, S = {}> {
243
new (props: P, context?: any): Component<P, S>;
244
displayName?: string;
245
defaultProps?: Partial<P>;
246
contextType?: Context<any>;
247
}
248
249
type ComponentProps<C extends ComponentType<any> | keyof JSXInternal.IntrinsicElements> =
250
C extends ComponentType<infer P>
251
? P
252
: C extends keyof JSXInternal.IntrinsicElements
253
? JSXInternal.IntrinsicElements[C]
254
: {};
255
```