Set up a UI Project

To start, clone the default UI project using git:

The example above clones Antora’s default UI project and then switches to the project folder on your filesystem. Stay in this project folder in order to initialize the project using npm.

Next, you’ll need to initialize the project. Initializing the project essentially means downloading and installing the dependencies into the project. That’s the job of npm.

In your terminal, execute the following command (while inside the project folder):

The npm i command, short for npm install, installs the dependencies listed in package.json into the node_modules/ folder inside the project. This folder does not get included in the UI bundle. The folder is safe to delete, though npm does a great job of managing it.

You’ll notice another file which seems to be relevant here, package-lock.json. npm uses this file to determine which concrete version of a dependency to use, since versions in package.json are typically just a range. The information in this file makes the build reproducible across different machines and runs.

Installing the dependencies makes the npx gulp command available. You can verify this by querying the Gulp version:

If a new dependency must be resolved that isn’t yet listed in package-lock.json, npm will update this file with the new information when you run npm i. Therefore, you’re advised to commit the package-lock.json file into the repository whenever it changes.

Now that the dependencies are installed, you should be able to run the gulp command to find out what tasks the build supports:

You should see:

We’ll explain what each of these tasks are for and when to use them.