[![Build Status](https://lt-devtool.visualstudio.com/Duet%20Design%20System/_apis/build/status/Duet%20Design%20System?branchName=master)](https://lt-devtool.visualstudio.com/Duet%20Design%20System/_build/latest?definitionId=58&branchName=master)
[![Version](https://img.shields.io/npm/v/@duetds/cli.svg?style=flat-square&label=cli)](https://www.npmjs.com/package/@duetds/cli)

# Duet Design System CLI

This package includes Duet Design System CLI, project templates, and related tools.

## Usage

For usage instructions, please see Duet Design System [documentation](https://www.duetds.com/cli/).

## Architecture

This package exports a CLI program `create-duet-app`. It streamlines the process of creating projects using Duet, and deploying password-protected prototype to github pages, by offering a number of boilerplate templates:

* Vanilla HTML/JavaScript
* 11ty
* 11ty SSR
* React
* Angular

Running `create-duet-app` does the following:

1. Prompts to select a template
1. Prompts to enter a name for the project
1. Prompts to initialise a git repository
1. Copies selected template to the named directory
1. Copy `shared/template.*` to named directory (renaming to remove "template" prefix)
1. Copy `shared/.github/workflows` to named directory
1. Install dependencies

### Github pages

The CLI offers the ability to easily deploy password-protected apps/prototypes to github pages.

For information on how to deploy a prototype to github pages please see [Sharing Prototypes](https://www.duetds.com/sharing-prototypes/)

For technical and architectural information, please see the [architecture](architecture.md) document.

### How to add new templates

A template has these minimum requirements:

* A unique directory under `templates/`.
* A readme explaining the template, and how to use
* A `package.json` (see below for further requirements)
* Content and URL structure roughly matching existing templates:
    * Duet Fonts, tokens, CSS framework included and ready to use
    * Use `latest` for all Duet dependencies in `package.json`

The `package.json` has the following requirements:

1. Have as `devDependencies` the following packages: `crypto-js`, `yargs`, `replace-in-file`, `npm-run-all`, `ncp`
1. Include a script named `build:prototype` in the `scripts` field. This is script is called by github actions to build and deploy to github pages

The `build:prototype` script must meet the following requirements:

1. It must build the project for production
1. It must output to a directory named `/dist/$DUET_TOKEN`
1. It must ensure all assets and links are relative to `/$DUET_PROJECT_NAME/$DUET_TOKEN`
    * In the react template, this is done by setting the `PUBLIC_URL` environment variable before calling `react-scripts build`
    * In Angular this is done by passing `--baseHref=/$DUET_PROJECT_NAME/$DUET_TOKEN/` as a flag to the `ng` command
    * How this is done varies depending on the technology used in the template
1. After the build is complete, it must run the following code `node ./.github/workflows/encrypt.js $DUET_TOKEN [passphrase]`, where `[passphrase]` is your chosen password

## Copyright

Copyright © 2020 LocalTapiola/Turva.
