You will need to install Node.js before working on this project.
- Clone the repository using
git clone https://github.com/cipscis/orange-twist.git. - Run
npm installto install development dependencies. - Create a
.envfile. - Run
npm startto 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 serverruns a Node.js server on the port specified in the.envfile, using Express. -
npm run buildcompiles CSS files using sass, then typechecks TypeScript using the TypeScript compiler and bundles TypeScript and any JavaScript using esbuild. -
npm run watchcompiles both CSS and TypeScript+JavaScript files just likenpm 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 lintlints all JavaScript and TypeScript files using eslint and all SCSS files using stylelint. -
npm startruns both theserverandwatchtasks simultaneously. -
npm testruns any configured test suites using Jest. -
npm run test:coverageruns any configured test suites using Jest, and reports coverage information. -
npm run watch:testruns any configured test suites using Jest in watch mode.
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"
SHOW_FPS = "false"
This file is intended to differ from environment to environment, so it is ignored by Git.
-
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.
These dependencies are used when working on the project locally.
-
Node.js: Runtime 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-modulesNode 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 63F5 some browser APIs that aren't implemented in jsdom
-
-
esbuild: Bundling tool
-
Express: Running a Node.js server, accessed at
http://localhost:<PORT> -
Concurrently: Running server and development build tasks concurrently
-
eslint: Linting TypeScript files
-
@typescript-eslint/eslint-plugin: Allows
eslintto lint TypeScript -
@typescript-eslint/parser: Allows
eslintto 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
-
eslint-plugin-jsdoc: Provides a linting rule making it easier to import type symbols for use in documentation comments
-
@eslint/compat: Use to make older eslint plugins work with the latest version
-
@eslint/eslintrc: Used to help define the eslint config
-
@eslint/js: eslint's JavaScript configuration, used as a base for eslint config
-
globals: Defines global variables for different environments, used by eslint
-
-
stylelint: Linting CSS
- stylelint-config-recommended-scss: Allows
stylelintto lint SCSS files, and provides a base set of SCSS linting rules
- stylelint-config-recommended-scss: Allows
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.