Nonlinear Programming Methods

    tech-radar-generator

    0.5.2 • Public • Published

    Build Status npm

    Tech Radar Generator

    A library for creating a ThoughtWorks Tech Radar as a static site. This project was forked from the ThoughtWorks Build-Your-Own-Radar app, but modified for distribution as a reusable package.

    Overview

    A tech radar is an app for visualising trends within an area of software development. They reflect the opinions and decisions of the creators and curators of the radar, and by their nature are highly subjective. They are generally used to reflect the technology decisions and future technical directions within a company, team, or project. A more in-depth discussion of why you might want to build a Tech Radar, and the design decisions for the original ThoughtWorks tech radar, are given here.

    This library is a tool for generating your own custom tech radar. The library provides a CLI script and a Node API which takes in as input a JSON file containing the data behind your radar, and outputs a directory with HTML, JS, and other static assets required to view the radar. The generated assets can then be served as a static site.

    Creating a radar with JSON

    First, create a JSON file containing the data behind your tech radar. This data is validated against a JSON schema before being processed, and the blips array uses the same API as the original tech radar.

    The top-level JSON must contain the following properties:

    • title - string - The title of the radar, which appears in the page title and the header of the page
    • quadrants - string[] - An array of exactly four quadrant names in the radar, rendered anti-clockwise from the top-right
    • rings - string[] - An array of up to four rings in the radar, from inner-most to outer-most
    • blips - blip[] - An array of blip objects determining the items appearing on the radar

    Each blip object must contain the following properties:

    • name - string - The name of the blip
    • quadrant - string - The quadrant of the radar that the blip appears in. There should be exactly four different quadrants in the full list of blips.
    • ring - string - The ring of the radar that the blip should appear in. This must take one of the provided ring values.
    • isNew - boolean - Set to true if the blip has been created or modified recently
    • description - string - A short description of the blip which appears when the blip is selected in the radar. This field can include HTML, and should include links to any supporting information or resources about the blip, and an explanation of why it's classified in the current ring.

    For example:

    {
      "title": "My Radar",
      "quadrants": ["Quad1", "Quad2", "Quad3", "Quad4"],
      "rings": ["adopt", "trial", "assess", "hold"],
      "blips": [
        {
          "name": "JavaScript",
          "quadrant": "Quad1",
          "ring": "adopt",
          "isNew": false,
          "description": "<p>This is a description</p><p>Formatted into paragraphs</p>"
        },
        {
          "name": "Go",
          "quadrant": "Quad2",
          "ring": "trial",
          "isNew": true,
          "description": "This is a simple description"
        },
        {
          "name": "Java",
          "quadrant": "Quad3",
          "ring": "assess",
          "isNew": false,
          "description": "This is a <a href=\"/\">description</a><br /><br />Spanning several lines."
        },
        {
          "name": "C++",
          "quadrant": "Quad4",
          "ring": "hold",
          "isNew": false,
          "description": "This is another simple description"
        }
      ]
    }

    Usage with the CLI

    To use this JSON data with the CLI, install the library and run it against the JSON file. If this tool is being incorporated into an existing JavaScript project:

    > yarn add tech-radar-generator
    > yarn tech-radar-generator ./my-radar.json ./dist

    If this tool is not being incorporated into a JavaScript project, the package can be run using npx:

    > npx tech-radar-generator ./my-radar.json ./dist

    The options for the CLI tool can be seen by running npx tech-radar-generator --help:

    > npx tech-radar-generator --help
    tech-radar-generator <input> <output>
    
    Builds a tech radar
    
    Positionals:
      input   the path to a valid JSON config input                         [string]
      output  the path to output the generated dist                         [string]
    
    Options:
      --version  Show version number                                       [boolean]
      --dev, -d  build in development mode                                 [boolean]
      --help     Show help                                                 [boolean]

    Usage within Node

    This library also exports a function version of the CLI, which takes the data, destination, and options as arguments and returns a promise resolving to the output directory.

    const techRadarGenerator = require('tech-radar-generator')
    const data = require('./my-radar.json')
    
    techRadarGenerator(data, './dist', { mode: 'development' })
      .then(dist => {
        console.log(`Successfully compiled to ${dist}`)
        process.exit(0)
      })
      .catch(err => {
        console.error(err)
        process.exit(1)
      })

    Unlike the CLI, this function takes the source data as a JavaScript object, and not as a file path. The input and output arguments are required. The third argument is an optional "options" object, and takes the following properties:

    • mode: 'development' or 'production' - The Webpack development mode. When set to "production", the code is minified, but takes longer to process. Defaults to "production".

    Usage with Docker

    An example Dockerfile with an nginx config:

    # Dockerfile
    
    FROM node:12 as build
    WORKDIR /build
    RUN yarn global add tech-radar-generator@0.4
    COPY example-data.json /build/
    RUN tech-radar-generator example-data.json /build/dist
    
    FROM nginx:1.17.3
    WORKDIR /opt/radar
    COPY nginx.conf /etc/nginx/conf.d/default.conf
    COPY --from=build /build/dist .
    CMD ["nginx", "-g", "daemon off;"]
    # nginx.conf
    
    # server block for static file serving
    server {
      listen 8080;
      location / {
        root /opt/radar;
        index index.html;
      }
    
      # custom error page for 404 errors
      error_page 404 /error.html;
      location = /error.html {
        root /opt/radar;
      }
    
      # nginx default error page for 50x errors
      error_page 500 502 503 504 /50x.html;
      location = /50x.html {
        root /usr/share/nginx/html;
      }
    }

    To build and run the image:

    > docker build --tag my-tech-radar:0.4 .
    > docker run -p8080:8080 my-tech-radar:0.4

    Developing

    This tool is powered by Webpack. Some commonly-used scripts are set in the npm-scripts.

    To run the webpack-dev-server:

    yarn dev
    

    To run the tests:

    yarn test
    

    To run the linter:

    yarn lint
    

    To format the code using standard:

    yarn format
    

    Releasing

    Releases to NPM are performed via Travis when tagged commits are pushed to the repo. Create a new tagged commit and bump the version in package.json with the npm version script:

    npm version patch

    and push the new commits and tags with:

    git push && git push --tags

    Acknowledgements

    This library is based off of the ThoughtWorks Build-Your-Own-Radar project.

    Keywords

    Install

    npm i tech-radar-generator

    DownloadsWeekly Downloads

    90

    Version

    0.5.2

    License

    AGPL-3.0

    Unpacked Size

    156 kB

    Total Files

    52

    Last publish

    Collaborators

    • dprgarner