Home Office plugin for GOV.UK prototypeHome Office React prototypeCommunity resources

PrototypingSet up your prototype

Rapidly create HTML prototypes of internal Home Office services.

If your team is planning to use the Home Office design system production framework, consider having the developers create a blank 'app' within the project to make it easier to transform your prototype into a production application.

Before you start

Mac users can use the Terminal application. It's located in the Utilities folder in Applications.

Windows users should install Git Bash (direct download) to use these app-instructions.

You'll need:

  • Node.js (version 18) - you can use version 16 too
  • a GitHub account
  • optionally a Heroku account, to publish your prototype
  • terminal - an application to install, start and stop a prototype. Using a terminal is sometimes called ‘using the command line’
  • a text editor, such as VSCode

To install Node.js or a text editor, you'll need administrator access to your computer.

Create your GitHub and Heroku accounts with any email address, including your Home Office email addresses.

Step 1. Set up your GitHub repository

This is where your prototype code will be stored.

  1. Log into your GitHub account.
  2. Create a new repository.
  3. If it's a Home Office prototype, select UKHomeOffice as the repository owner.
  4. Enter a repository name. For our example, we'll use review-licence-applications as the repository name.
  5. Select public for the privacy.
  6. Do not add a README, a .gitignore or a license, these will come later.
GitHub screen showing text field with new repository name mock wildcat service

We'll connect this blank remote GitHub repository with the prototype you'll create in the next step.

Step 2. Create a prototype

Run the prototype generator in terminal

You can use any name you like for your prototype folder, in this example we'll use review-licence-applications.

Open terminal and enter these commands:

  1. Run mkdir review-licence-applications (literally make directory) to create a folder for your prototype. You can see this folder in File Explorer on Windows or Finder on Mac. Nothing will show in terminal.
  2. Run cd review-licence-applications (literally change directory) to move your terminal inside your prototype folder. You should see your current folder has changed in terminal.
  3. Run npm init @hods prototype to create the prototype. You'll see:
    Need to install the following packages: @hods/create Ok to proceed? (y)
  4. Press enter to continue.
  5. Answer the prompts. Accept the default answers, by pressing enter.
    Terminal screen with asking for the short name, long name, version, description and licence needed to set up the prototype
    You'll see a lot of text in the terminal, it'll end with ✔ message Done..

Download the dependencies

Run npm install to download the dependencies to make your prototype work. These are stored in the node_modules folder. They are specific to this prototype and do not affect any of your other prototypes.

View the prototype locally

In terminal, enter:

npm run dev

When your terminal returns a message that says:

No issues found.

You can view the prototype by opening http://localhost:8080/ in your web browser. This will help you track changes locally as you build your prototype.

Step 3. Share your prototype on GitHub

Once installation is complete, you can share your prototype on GitHub.

  1. Run git init to create (or initialise) a local git repository.
  2. Run git add . to locally stage the initial files ready for commit.
  3. Run git commit -m "initial commit" to locally commit the initial files.
  4. Go to your blank GitHub repository.
  5. Find the section on 'push an existing repository'.
  6. Copy the 3 lines of code, and run them in your terminal.

If you can't find the lines of code, use these replacing YOUR_GITHUB_NAME with your user name:

  1. git remote add origin git@github.com:YOUR_GITHUB_NAME/review-licence-applications.git to add a remote git repository called 'origin'.
  2. git branch -M main to rename your local branch called 'master' to 'main'.
  3. git push -u origin main to publish your local main branch to the main branch of your remote repository called 'origin'.

Next: Build your prototype

Help us improve prototyping guidance

This needs improving. We need evidence about:

  • your experience using this kit

To contribute, add your thoughts and research findings to our GitHub discussion, or follow our contribute guidance.