FileIO

Install

Run npm install @cipscis/fileio

Usage

See FileIO documentation

Development

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

1. Clone the repository using git clone https://github.com/cipscis/fileio.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 testCoverage runs any configured test suites using Jest, and reports coverage information.

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

.env

The .env file contains the following environment variables:

• PROJECT_NAME (string)

If present, used by Express to set up redirects for emulating GitHub Pages.

• MODE (string 'development' | 'production')

Used by Webpack to determine what optimisations to use and how to generate sourcemaps.

• PORT (int)

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

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

PROJECT_NAME = "fileio"
MODE = "development"
PORT = "8080"

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

Dependencies

None.

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

  • ts-jest-resolver: Allows ESM modules imported in TypeScript tests to be resolved using TypeScript's rules, e.g. 'code.js' may fine 'code.ts'

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

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

• 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

• stylelint: Linting CSS

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

• rimraf: For deleting the contents of the dist folder prior to compilation

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.

• Deploy to GitHub Pages: Used to deploy the project to GitHub pages once it has been built