This is my template repository to use when creating new projects. The top section of this readme is for how to use it to start a new project, and should be removed as part of the setup process.
You will need to install Node.js before using this template.
- Click "Use this template" to create a new repository based on this one.
- Update the
package.json
file to reflect your new project's details. - Update names throughout the package.
a. Replace
base-project
with the name of your project as it is used in code. b. ReplaceBase Project
Replace with the name of your project as it is used in documentation. c. If you're not me, replace@cipscis
with your npm username and thencipscis
with your GitHub username, and be sure to also update theauthor
property in thepackage.json
. - Create a
.env
file. See .env for more information. - Run
npm install
. - Update this
README.md
file and theCHANGELOG.md
file to remove the instruction sections.
Now you're ready to work on code in this project.
Using the files specified in package.json
, you can create a project to be installed with npm.
In the app
folder, which can be deployed to GitHub Pages but is not included when your project is installed, you can document your project. Here, the project files outside the app
folders can be included in the bundle by using root-relative paths such as import foo from '/main.js';
Once you have an initial version of your project ready to push, you will want to update the version
attribute of your package.json
file to "1.0.0"
. See Semantic Versioning for more information on version numbers.
You should also update the CHANGELOG.md
file to describe your changes. This is particularly important after your initial 1.0.0 version.
Assets such as CSS and JavaScript are contained in /app/assets
. In here, the contents of the scss
folder are used to compile CSS files into the css
folder.
The /app/assets/js
folder contains a src
folder and a dist
folder. Any JavaScript or TypeScript files inside the src
folder are bundled into the dist
folder. By default, eslint is configured to look for a single entry point at /app/assets/js/src/main.ts
.
Node.js code sits within the /scripts
directory. This includes the build system, which uses esbuild, as well as the Express server code.
The build system's entry points are defined within build-config.ts
.
By default, the server code just runs a static http server that serves files in the /app
directory, but it can be extended to add additional functionality.
This server only runs locally, so any additional functionality will not be available on GitHub Pages.
By default, the package.json
file is configured to set the project to be of type module
. This means NodeJS will use ES module syntax as opposed to its default CommonJS syntax, allowing the use of import
and export
keywords.
For more information on the differences, see Differences between ES modules and CommonJS
eslint is configured in .eslintrc.cjs
, and stylelint is configured in stylelint.config.cjs
The Jest-based test suite is configured in jest.config.js. No custom test name matcher is specified, which means Jest's default matcher will be used:
By default it looks for
.js
,.jsx
,.ts
and.tsx
files inside of__tests__
folders, as well as any files with a suffix of.test
or.spec
(e.g.Component.test.js
orComponent.spec.js
). It will also find files calledtest.js
orspec.js
.
If any extra setup needs to be done before tests are run, such as polyfilling functionality not supported by jsdom
, code for this can be placed in jest.setup.ts.
See .env for information on setting up a .env
file.
This project is set up to use a GitHub Action every time new code is pushed to the main
branch. This build-and-deploy
workflow runs the build
npm script, then runs the test script, then if the tests passed it deploys the contents of the app
directory directly to GitHub Pages.
In order to allow the main
branch to be used to publish to GitHub Pages, you need to set up an environment called github-pages
in the settings for your project. This environment should be configured to allow branches with the name pattern main
to deploy to GitHub Pages.
When publishing a project using GitHub Pages, if you are not using a custom domain the project usually appears at a URL with a path, such as https://cipscis.github.io/base-project
. This means using root relative URLs such as /assets/css/main.css
would work locally, but would break when the project is published on GitHub Pages.
To fix this, the local Node.js server looks for a PROJECT_NAME
variable in your .env
file. If it finds one, it sets up rewrites so you will need to use the same /${PROJECT_NAME}/
paths during local development as would be required by GitHub Pages.
By default, the index.html
file is configured to be published to GitHub Pages under the project name base-project
. When you use it as a base for your own project, you will need to update these URLs.
If you are publishing to GitHub Pages using a custom domain, you can remove the PROJECT_NAME
variable from your [.env](#env-1) file and any
/${PROJECT_NAME}/` paths specified in other files.
Delete everything above here when creating a new project
You will need to install Node.js before working on this project.
- Clone the repository using
git clone https://github.com/cipscis/base-project.git
. - Run
npm install
to install development dependencies. - Create a
.env
file. - 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 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 lint
lints all JavaScript and TypeScript files using eslint and all SCSS files using stylelint. -
npm start
runs both theserver
andwatch
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.
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: '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.
An example .env
file you can use for development is:
PROJECT_NAME = "base-project"
MODE = "development"
PORT = "8080"
This file is intended to differ from environment to environment, so it is ignored by Git.
None.
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/jest-dom: Utilities for DOM tests using Jest
-
@testing-library/user-event: Utilities for simulating user interaction during tests
-
-
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
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
- 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-pages-artifact: Used to upload an artifact to use for deploying to GitHub Pages.
-
deploy-pages: Used to deploy the artifact to GitHub Pages.