orange-twist

Orange Twist

Development

You will need to install Node.js before working on this project.

1. Clone the repository using git clone https://github.com/cipscis/orange-twist.git.
2. Run npm install to install development dependencies.
3. Create a .env file.
4. Run npm start to run the local server and watch CSS and JS files for changes.

Usually, you will just want to run npm start, but this project also provides the following npm scripts:

• npm run server runs a Node.js server on the port specified in the .env file, using Express.

• npm run build compiles CSS files using sass, then typechecks TypeScript using the TypeScript compiler and bundles TypeScript and any JavaScript using esbuild.

• npm run watch compiles both CSS and TypeScript+JavaScript files just like npm run build, but in watch mode so any further changes will result in recompilation. Also runs any configured tests suites in watch mode.

• npm run lint lints all JavaScript and TypeScript files using eslint and all SCSS files using stylelint.

• npm start runs both the server and watch tasks simultaneously.

• npm test runs any configured test suites using Jest.

• npm run test:coverage runs any configured test suites using Jest, and reports coverage information.

• npm run watch:test runs any configured test suites using Jest in watch mode.

.env

The .env file contains the following environment variables:

• MODE: 'development' | 'production'

Used to determine what optimisations to use when running the build process.

• PORT: number

Used by Express to determine which port to use when running a local Node.js server.

• SHOW_FPS?: boolean

If true, an FPS counter will display in the top left corner in development mode.

An example .env file you can use for development is:

MODE = "development"
PORT = "8080"

This file is intended to differ from environment to environment, so it is ignored by Git.

Dependencies

• Preact: Rendering framework, alternative to React.

• preact-render-to-string: Preact's server-side rendering framework.

• zod: A library for writing type schemas, designed for working with TypeScript.

• marked: A Markdown compiler.

• marked-highlight: A plugin for marked that allows syntax highlighting to be applied.

• highlight.js: A library for providing syntax highlighting to code.

Dev Dependencies

Development

These dependencies are used when working on the project locally.

• Node.js: Runtime environment

• ts-node: Allows TypeScript code to be run in a Node.js environment

• npm: Package manager

• TypeScript: JavaScript extension for static type checking

• Jest: Testing framework

  • @jest/globals: Allows Jest utilities to be imported instead of polluting the global scope

  • cross-env: Used for setting the --experimental-vm-modules Node CLI flag to allow Jest to work with ESM modules

  • jest-environment-jsdom: Mocks a DOM environment to allow testing code that uses DOM APIs

  • ts-jest: Allows Jest tests to be written in TypeScript

  • @testing-library/preact: Testing library for Preact

  • @testing-library/jest-dom: Utilities for DOM tests using Jest

  • @testing-library/user-event: Utilities for simulating user interaction during tests

  • jsdom-testing-mocks: Mocks some browser APIs that aren't implemented in jsdom

• esbuild: Bundling tool

• sass: Compiling CSS from Sass

• Express: Running a Node.js server, accessed at http://localhost:<PORT>

• Concurrently: Running server and development build tasks concurrently

• dotenv: Reading environment variables from .env file

• eslint: Linting TypeScript files

  • @typescript-eslint/eslint-plugin: Allows eslint to lint TypeScript

  • @typescript-eslint/parser: Allows eslint to parse TypeScript

  • @stylistic/eslint-plugin: Provides linting rules to enforce code style

  • eslint-plugin-react: Provides React/Preact linting rules

  • eslint-plugin-react-hooks: Provides React/Preact linting rules

  • eslint-plugin-jest: Provides Jest linting rules

  • eslint-plugin-import-newlines: Provides a linting rule for named imports

• stylelint: Linting CSS

  • stylelint-config-recommended-scss: Allows stylelint to lint SCSS files, and provides a base set of SCSS linting rules

Deploy

These dependencies are used for deploying the project to GitHub Pages.

• checkout: Used to check out the repository to a workspace so it can be built.

• setup-node: Use to set up a Node.JS environment for the build and test scripts to run on during the deployment process.

• upload-artifact: Used to upload a build artifact to be reused across multiple CI/CD jobs.

• download-artifact: Used to download a build artifact.

• upload-pages-artifact: Used to upload an artifact to use for deploying to GitHub Pages.

• deploy-pages: Used to deploy the artifact to GitHub Pages.