Getting started

Before you begin

This guide introduces you to the Ontario.ca Frontend by walking you through building a sample project. The tutorial is divided into several sections:

Setting up your local development environment will get you ready to build an application
Creating a new project will create a new Ontario.ca Frontend project
Building and serving your app will serve your application locally, confirming that you are ready for development
Reviewing your new project will acquaint you with the files and structure that make up a new Ontario.ca Frontend project
Updating your content will step you through changing your page's <h1> and the content displayed below that heading

Prerequisites

You will need familiarity with HTML, CSS, and JavaScript. In addition, you will need to have the following installed:

The current LTS release of Node.js

Setting up your local development environment

Verify your version of Node.js

Identify your version of Node.js from a terminal window:

Terminal

node --version

Identify the version of Node.js used by Ontario.ca Frontend. This can be found from the engines property in the package.json file.

If you do not have Node.js installed, or do not have a version that meets the Ontario.ca Frontend prerequisites, it will need to be installed. Installation directions can be found on nodejs.org.

Install a code editor

You will need access to a code editor to write, edit, and manage your project's source code. Popular code editors include applications like Visual Studio Code or Sublime Text.

It doesn’t matter what code editor you choose to use. Your project will end up looking the same no matter what tool you use. (However, the Ontario.ca Frontend team uses Visual Studio Code.)

Creating a new project

To create a new Ontario.ca Frontend project on a your workstation, use the following command:

Terminal

npx @ongov/ontario-frontend-cli ontario-create-app

This command will start the automatic project setup process, which will walk you through the process of setting up a new project from scratch using interactive prompts.

The first prompt will request the name for your project. This will be used for the project's directory, as well as in the project's package.json. Project names must only include lowercase, hyphens, and underscores. If nothing is entered, then the default my-frontend-project will be used.

Terminal

What is your project named? (my-frontend-project)

When choosing a name for your project, make sure it is:

not an empty string
uses only lowercase characters (no uppercase or mixed case names are allowed)
does contain any non-URL-safe characters
does not start with . or _
does not contain any spaces
does not contain any of the following characters: ~)('!*

The next prompt will request the name for your English-language page. This value will be used for the file name of the English page, it will also be used as the English URL for your app on Ontario.ca. A value must be entered, no defaults are provided.

Terminal

What is the file name for the English-language page? (This will be used for the path, e.g. ontario.ca/my-english-page): (english)

For the sake of this tutorial, enter "english".

The next prompt, similar to the previous prompt, will request the name for your French-language page. This value will be used for the file name of the French page, it will also be used as the French URL for your app on Ontario.ca. A value must be entered, no defaults are provided.

Terminal

What is the file name for the French-language page? (This will be used for the path, e.g. ontario.ca/ma-page-francaise): (francais)

For the sake of this tutorial, enter "francais".

When the prompt asks, "Add and configure ESLint for finding and fixing code problems?" use the arrow key to select "No" (we can add this to our project later.)

Terminal

Add and configure ESLint for finding and fixing code problems? No

Similarly, when the prompt asks "Add and configure Prettier for opinionated code formatting?" use the arrow key to select "No" (we can also add this later).

Terminal

Add and configure Prettier for opinionated code formatting? No

Once you have responded to all the prompts, the automatic project setup process will use the information you provide to scaffold out your new project repository, set up all necessary files and configuration, and install all necessary dependencies.

Building and serving your app

After you have created your new project, you should build and serve the application to verify that your local development environment is correctly set up.

Within your terminal:

Navigate to your project's directory from the command line. This was defined previously, during the 'Creating a new project' step.
Type the command npm run serve into the command line and hit the "Enter" key to run it. After a few moments, the command line should output a message telling you your development server is being served at http://localhost:8080.
Open a web browser on your computer and navigate to http://localhost:8080.

You should see your Ontario.ca Frontend project running locally in your browser.

You’ll be able to visit the site locally at http://localhost:8000/ for as long as the development server is running. (That’s the process you started by running the npm run serve command.) You can leave the development server running while you develop your application. In most cases, making changes to the code in your project will be automatically detected and the app will reload in the web browser.

To stop running that process (or to “stop running the development server”), go back to your terminal window, hold down the “control” key, and then hit “c” (ctrl-c). To start it again, run npm run serve again.