0
# Stencil Core
1

2
Stencil is a comprehensive web component compiler that transforms TypeScript and JSX code into standards-compliant web components. Built by the Ionic team, it provides a complete development toolchain including a TypeScript-based component authoring experience with decorators, a powerful build system with code splitting and lazy loading, integrated testing utilities, development server with hot reloading, and screenshot testing capabilities.
3

4
## Package Information
5

6
- **Package Name**: @stencil/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @stencil/core`
10

11
## Core Imports
12

13
Main component development imports:
14

15
```typescript
16
import { Component, Prop, State, h } from '@stencil/core';
17
```
18

19
For configuration and build setup:
20

21
```typescript
22
import { Config } from '@stencil/core';
23
```
24

25
For testing:
26

27
```typescript
28
import { newSpecPage, newE2EPage } from '@stencil/core/testing';
29
```
30

31
For compiler and build tools:
32

33
```typescript
34
import { createCompiler } from '@stencil/core/compiler';
35
```
36

37
For mock document utilities:
38

39
```typescript
40
import { MockDocument } from '@stencil/core/mock-doc';
41
```
42

43
For screenshot testing:
44

45
```typescript
46
import { ScreenshotConnector } from '@stencil/core/screenshot';
47
```
48

49
For Node.js system utilities:
50

51
```typescript
52
import { NodeSystem } from '@stencil/core/sys/node';
53
```
54

55
For internal client-side APIs:
56

57
```typescript
58
import { BUILD } from '@stencil/core/internal/client';
59
```
60

61
## Basic Usage
62

63
```typescript
64
import { Component, Prop, State, h } from '@stencil/core';
65

66
@Component({
67
  tag: 'my-component',
68
  styleUrl: 'my-component.css',
69
  shadow: true,
70
})
71
export class MyComponent {
72
  @Prop() firstName: string;
73
  @Prop() lastName: string;
74
  @State() private isVisible: boolean = true;
75

76
  render() {
77
    return (
78
      <div>
79
        <p>Hello, {this.firstName} {this.lastName}!</p>
80
        {this.isVisible && <button onClick={() => this.toggle()}>Toggle</button>}
81
      </div>
82
    );
83
  }
84

85
  private toggle() {
86
    this.isVisible = !this.isVisible;
87
  }
88
}
89
```
90

91
## Architecture
92

93
Stencil is built around several key architectural components:
94

95
- **Component System**: Decorator-based component authoring with @Component, @Prop, @State, and lifecycle hooks
96
- **Compiler**: TypeScript and JSX to standards-compliant web components compilation
97
- **Build System**: Multiple output targets (www, dist, custom elements) with optimization and code splitting
98
- **Runtime**: Lightweight runtime for component hydration and rendering with virtual DOM
99
- **Testing Framework**: Unit testing with Jest integration and E2E testing with Puppeteer
100
- **Development Tools**: Dev server with HMR, documentation generation, and debugging utilities
101

102
## Capabilities
103

104
### Component Development
105

106
Core decorators and utilities for creating web components with TypeScript and JSX.
107

108
```typescript { .api }
109
// Component decorators
110
function Component(opts: ComponentOptions): ClassDecorator;
111
function Prop(opts?: PropOptions): PropertyDecorator;
112
function State(): PropertyDecorator;
113
function Watch(propName: string): MethodDecorator;
114
function Method(opts?: MethodOptions): MethodDecorator;
115
function Element(): PropertyDecorator;
116
function Event(opts?: EventOptions): PropertyDecorator;
117
function Listen(eventName: string, opts?: ListenOptions): MethodDecorator;
118
function AttachInternals(): PropertyDecorator;
119

120
// JSX and rendering utilities
121
function h(sel: any, data?: VNodeData | null, ...children: any[]): VNode;
122
declare const Host: FunctionalComponent<HostAttributes>;
123
declare const Fragment: FunctionalComponent<{}>;
124
function render(vnode: VNode, container: Element): void;
125
```
126

127
[Component Development](./component-development.md)
128

129
### Build Configuration
130

131
Configuration system for the Stencil compiler including output targets, dev server, and build optimization.
132

133
```typescript { .api }
134
interface Config extends StencilConfig {
135
  outputTargets?: OutputTarget[];
136
  devServer?: StencilDevServerConfig;
137
  testing?: TestingConfig;
138
  globalStyle?: string;
139
  namespace?: string;
140
  buildEs5?: boolean | 'prod';
141
}
142

143
interface ComponentOptions {
144
  tag: string;
145
  styleUrl?: string;
146
  styleUrls?: string[] | ModeStyles;
147
  styles?: string | { [modeName: string]: any };
148
  shadow?: boolean | ShadowRootOptions;
149
  scoped?: boolean;
150
  assetsDirs?: string[];
151
  formAssociated?: boolean;
152
}
153
```
154

155
[Build Configuration](./build-configuration.md)
156

157
### Testing Utilities
158

159
Comprehensive testing framework with unit testing, E2E testing, and screenshot testing capabilities.
160

161
```typescript { .api }
162
// Spec testing
163
function newSpecPage(opts: NewSpecPageOptions): Promise<SpecPage>;
164

165
// E2E testing  
166
function newE2EPage(opts?: NewE2EPageOptions): Promise<E2EPage>;
167

168
// Mock utilities
169
function mockBuildCtx(): BuildCtx;
170
function mockCompilerCtx(): CompilerCtx;
171
function mockConfig(): Config;
172
function mockDocument(): Document;
173
function mockWindow(): Window;
174

175
interface SpecPage {
176
  body: HTMLElement;
177
  doc: Document;
178
  root?: HTMLElement;
179
  rootInstance?: any;
180
  setContent(html: string): Promise<void>;
181
  waitForChanges(): Promise<void>;
182
}
183
```
184

185
[Testing Utilities](./testing-utilities.md)
186

187
### Runtime Utilities
188

189
Runtime functions for asset management, mode handling, task scheduling, and component utilities.
190

191
```typescript { .api }
192
// Asset management
193
function getAssetPath(path: string): string;
194
function setAssetPath(path: string): string;
195

196
// Mode and environment
197
function getMode<T = string | undefined>(ref: any): T;
198
function setMode(handler: ResolutionHandler): void;
199
declare const Build: UserBuildConditionals;
200
declare const Env: { [prop: string]: string | undefined };
201

202
// Task scheduling
203
function writeTask(task: RafCallback): void;
204
function readTask(task: RafCallback): void;
205

206
// Component utilities
207
function getElement(ref: any): HTMLStencilElement;
208
function forceUpdate(ref: any): void;
209
function getRenderingRef(): any;
210

211
// Platform configuration
212
function setNonce(nonce: string): void;
213
function setErrorHandler(handler: ErrorHandler): void;
214
function setPlatformHelpers(helpers: PlatformHelpers): void;
215
```
216

217
[Runtime Utilities](./runtime-utilities.md)
218

219
### Compiler API
220

221
Advanced compiler APIs for build tools, plugins, and custom integrations.
222

223
```typescript { .api }
224
interface Compiler {
225
  build(): Promise<CompilerBuildResults>;
226
  createWatcher(): Promise<CompilerWatcher>;
227
  destroy(): Promise<void>;
228
  sys: CompilerSystem;
229
}
230

231
interface CompilerSystem {
232
  name: 'node' | 'in-memory';
233
  version: string;
234
  readFile(p: string): Promise<string>;
235
  writeFile(p: string, content: string): Promise<CompilerSystemWriteFileResults>;
236
  access(p: string): Promise<boolean>;
237
  createDir(p: string): Promise<CompilerSystemCreateDirectoryResults>;
238
}
239

240
interface CompilerBuildResults {
241
  buildId: number;
242
  diagnostics: Diagnostic[];
243
  duration: number;
244
  hasError: boolean;
245
  hasSuccessfulBuild: boolean;
246
  outputs: BuildOutput[];
247
}
248
```
249

250
[Compiler API](./compiler-api.md)
251

252
### Development Server
253

254
Development server configuration and APIs for hot module replacement and live reloading.
255

256
```typescript { .api }
257
interface StencilDevServerConfig {
258
  address?: string;
259
  port?: number;
260
  basePath?: string;
261
  https?: Credentials;
262
  openBrowser?: boolean;
263
  reloadStrategy?: PageReloadStrategy;
264
  experimentalDevModules?: boolean;
265
  logRequests?: boolean;
266
  worker?: boolean;
267
}
268

269
interface DevServer extends BuildEmitEvents {
270
  address: string;
271
  port: number;
272
  browserUrl: string;
273
  close(): Promise<void>;
274
}
275
```
276

277
[Development Server](./development-server.md)
278

279
## Types
280

281
```typescript { .api }
282
// Core component interfaces
283
interface ComponentInterface {
284
  connectedCallback?(): void;
285
  disconnectedCallback?(): void;
286
  componentWillLoad?(): Promise<void> | void;
287
  componentDidLoad?(): void;
288
  componentWillUpdate?(): Promise<void> | void;
289
  componentDidUpdate?(): void;
290
  componentWillRender?(): Promise<void> | void;
291
  componentDidRender?(): void;
292
  componentShouldUpdate?(newVal: any, oldVal: any, propName: string): boolean | void;
293
  render?(): any;
294
}
295

296
// Virtual DOM types
297
interface VNode {
298
  $flags$: number;
299
  $tag$: string | number | Function;
300
  $elm$: any;
301
  $text$: string;
302
  $children$: VNode[];
303
  $attrs$?: any;
304
  $name$?: string;
305
  $key$?: string | number;
306
}
307

308
interface VNodeData {
309
  class?: { [className: string]: boolean };
310
  style?: any;
311
  [attrName: string]: any;
312
}
313

314
// Event system
315
interface EventEmitter<T = any> {
316
  emit: (data?: T) => CustomEvent<T>;
317
}
318

319
interface EventOptions {
320
  eventName?: string;
321
  bubbles?: boolean;
322
  cancelable?: boolean;
323
  composed?: boolean;
324
}
325

326
// Build conditionals
327
interface UserBuildConditionals {
328
  isDev: boolean;
329
  isBrowser: boolean;
330
  isServer: boolean;
331
  isTesting: boolean;
332
}
333

334
// Functional components
335
interface FunctionalComponent<T = {}> {
336
  (props: T, children: VNode[], utils: FunctionalUtilities): VNode | VNode[];
337
}
338

339
interface FunctionalUtilities {
340
  forEach: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => void) => void;
341
  map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[];
342
}
343

344
// Task queue
345
interface RafCallback {
346
  (timeStamp: number): void;
347
}
348

349
interface QueueApi {
350
  tick: (cb: RafCallback) => void;
351
  read: (cb: RafCallback) => void;
352
  write: (cb: RafCallback) => void;
353
  clear?: () => void;
354
  flush?: (cb?: () => void) => void;
355
}
356

357
// HTML element interface
358
interface HTMLStencilElement extends HTMLElement {
359
  componentOnReady(): Promise<HTMLStencilElement>;
360
}
361

362
// Error handling
363
type ErrorHandler = (err: any, element?: HTMLElement) => void;
364
type ResolutionHandler = (elm: HTMLElement) => string | undefined | null;
365

366
// Diagnostics
367
interface Diagnostic {
368
  level: 'error' | 'warn' | 'info' | 'log' | 'debug';
369
  type: string;
370
  messageText: string;
371
  absFilePath?: string;
372
  relFilePath?: string;
373
  lineNumber?: number;
374
  columnNumber?: number;
375
  lines: PrintLine[];
376
  header?: string;
377
  language?: string;
378
  code?: string;
379
  debugText?: string;
380
}
381

382
interface PrintLine {
383
  lineIndex: number;
384
  lineNumber: number;
385
  text?: string;
386
  html?: string;
387
  errorCharStart: number;
388
  errorLength?: number;
389
}
390
```