Skip to main content
Version: v5 (Preview)

Installation

Starting a New Project​

Prerequisites​

Stencil requires a recent LTS version of Node.js and a package manager (npm, pnpm, yarn, or bun). Make sure you've installed and/or updated Node before continuing.

Running the stencil init wizard​

The stencil init wizard scaffolds a new Stencil project. Run it through your package manager's create/init convention:

npm init stencil@next
note

While v5 is in preview, keep the @next tag. Without it, you get the Stencil v4 project generator.

stencil init is context-aware: run in an empty directory, it scaffolds a new project. Run inside an existing Stencil project, it switches to "add capabilities" mode instead, letting you install and configure integrations (testing, styling, framework output targets) you didn't set up initially - the same picker stencil add shows when you run it with no arguments.

The wizard walks you through a handful of questions - project name, which output targets you need, and which integrations (testing, styling, framework wrappers) to install and configure. Answering them installs the packages you chose and generates a project directory matching your project name.

It creates a project like this:

my-first-stencil-project/
├── src/
│   ├── components/
│   │   └── my-component/
│   │       ├── my-component.css
│   │       ├── my-component.tsx
│   │       └── usage/
│   │           └── example.md
│   └── utils/
│       └── utils.ts
├── .gitignore
├── package.json
└── tsconfig.json
note

The exact structure depends on the options you choose. With all the default options, there's no stencil.config.ts, since Stencil's defaults are all the project needs. Choosing a framework wrapper offers to set the project up as a monorepo, with this project in a packages/ folder.

Once it finishes, move into the new directory and start the dev server:

cd my-first-stencil-project
npm run dev

Useful Initial Commands​

A scaffolded project's package.json comes with a few scripts to get started:

  • npm run dev (stencil build --dev --watch --serve) starts a local development server with hot-module reloading, rebuilding your components in the browser as you edit them.
  • npm run build (stencil build) creates a production build of your components.
  • npm run generate (stencil generate, or stencil g) scaffolds a new component.

Unlike Stencil v4, a new project has no test setup by default - v5 has no integrated test runner. Add one through the wizard (stencil add, see below) when you're ready; @stencil/vitest is the recommended starting point for most projects.

Adding Capabilities Later​

Didn't set up testing, a framework output target, or a styling preprocessor when you first ran stencil init? Add one at any point with:

stencil add

Run without arguments, stencil add prompts you to pick from known integrations (like @stencil/vitest or @stencil/playwright) and any already-installed packages that expose their own setup wizard. You can also install a specific package directly: stencil add @stencil/vitest.

Updating Stencil​

To get the latest version of @stencil/core, run:

npm install @stencil/core@beta --save-exact
note

While v5 is in preview, it's published under the beta tag. @latest installs Stencil v4.

Next Steps​

With the project running, build your first component.

Contents

Edit this page