ionic-team / create-stencil

npm init stencil

The create-stencil CLI

create-stencil is a CLI for creating new Stencil projects based on predefined templates, or "starters". It is the official CLI maintained by the Stencil team, and is recommended for all new projects.

Prerequisites

The create-stencil CLI requires npm version 6 or higher to be installed. For instructions for installing or upgrading npm, please see the npm Documentation.

Starters

The create-stencil CLI offers the following starters for bootstrapping your project:

• component - allows one to spin up a component library containing one or more Stencil components. Best suited for teams/individuals looking to reuse components across one or more applications. (Source Code)
• app - allows one to spin up an application, complete with routing. This is a community-driven project, and is not formally owned by the Stencil team. (Source Code)
• ionic-pwa - allows one to spin up an Ionic PWA, complete with tabs layout and routing. This is a community-driven project, and is not formally owned by the Stencil team. (Source Code)

The CLI can also generate projects using starters that are not officially developed by Ionic or the Stencil Community. See the documentation for Command Mode for additional information on using additional templates.

Usage

The create-stencil CLI can be run in one of two modes - Interactive Mode or Command Mode.

Interactive Mode

Interactive Mode allows a user to interactively select options for creating a new Stencil project. create-stencil can be started in Interactive Mode by running:

$ npm init stencil

Running the CLI in Interactive Mode will prompt you to select one of the available starters to use:

$ npm init stencil

✔ Select a starter project.

Starters marked as [community] are developed by the Stencil Community,
rather than Ionic. For more information on the Stencil Community, please see
https://github.com/stencil-community › - Use arrow-keys. Return to submit.
❯   component                Collection of web components that can be used anywhere
    app [community]          Minimal starter for building a Stencil app or website
    ionic-pwa [community]    Ionic PWA starter with tabs layout and routes

Followed by a name for your new project:

✔ Project name > my-stencil-library

After confirming your selections, your project will be created. In this example, a new component library starter will have been copied into a newly created my-stencil-library directory:

✔ Confirm? … yes
✔ All setup  in 29 ms

  We suggest that you begin by typing:

  $ cd my-stencil-library
  $ npm install
  $ npm start

  You may find the following commands will be helpful:

  $ npm start
    Starts the development server.

  $ npm run build
    Builds your project in production mode.

  $ npm test
    Starts the test runner.


  Further reading:

   - https://github.com/ionic-team/stencil-component-starter
   - https://stenciljs.com/docs

  Happy coding! 🎈

Command Mode

Command Mode allows you to create a new Stencil project by specifying all project options upfront.

To run the CLI in Command Mode, a starter and project name must be specified:

npm init stencil [starter] [project-name]

An example of creating a component starter with the name "my-stencil-library" is shown below:

npm init stencil component my-stencil-library

In the example above, a new component library starter will have been created in a newly created my-stencil-library directory.

Custom Templates

In addition to the provided template options, users may choose to use one of their own custom templates hosted on GitHub.com.

To use a custom starter template, provide the GitHub repository owner and repository name as the starter name, using the format REPO_OWNER/REPO_NAME. For example, to retrieve a template that is owned by 'my-organization' that has the name 'my-stencil-template':

npm init stencil my-organization/my-stencil-template my-stencil-library

The command above will create a copy of the my-organization/my-stencil-template repository, and place it under my-stencil-library on disk.

This can be used in conjunction with Self Hosted GitHub Instances to use custom starter templates that live on a self-hosted GitHub instance.

Additional Flags

Note: When passing flags to the create-stencil CLI, a double dash ('--') must be placed between npm init stencil and the flag(s) passed to the CLI:

$ npm init stencil -- --help

--help, -h

The --help flag shows usage examples for the CLI.

--info

The --info will print the current version of the CLI.

Environment Variables

https_proxy

If you are behind a proxy, the https_proxy environment variable can be set when running the CLI:

$ https_proxy=https://[IP_ADDRESS] npm init stencil

Stencil uses https-proxy-agent under the hood to connect to the specified proxy server. The value provided for https_proxy will be passed directly to the constructor for a new HttpsProxyAgent instance.

stencil_self_hosted_url

In some scenarios, teams may find themselves working solely out of a self-hosted GitHub instance.

Users wishing to point the create-stencil CLI at a GitHub instance other than GitHub have two options:

1. Set stencil_self_hosted_url in your .npmrc file, like so:

   // .npmrc
   stencil_self_hosted_url=https://your_self_hosted_github_repo.com/
   

   Using this option, the CLI can be called as such, automatically picking up the value in stencil_self_hosted_url:

   npm init stencil [starter] [project-name]
   

2. Set stencil_self_hosted_url at invocation time:

   stencil_self_hosted_url=https://your_self_hosted_github_repo.com/ npm init stencil

   When using this option, stencil_self_hosted_url must always be set every time the CLI is called.

When both options are set, the value provided on the command line takes precedence over the value in your .npmrc file.

Citations

Original project was created by William M. Riley:

• Twitter
• Github

Related Links

• The Stencil Documentation site has more information on using Stencil.
• Check out the Stencil Discord for help and general Stencil discussion!