Nuxt 3 Starter

Note: This is a general purpose readme. Much of the language used is abstract enough for most contexts, but should be modified to fit the specific use case once this code instantiated from the Github template (e.g., which workspaces are actually used).

Overview

A starter repo for getting a Nuxt3 project up and running quickly. This project is structured as an NPM monorepo, and can be used to implement a backend, application UI, static microsite, or anything else.

Typically used workspaces in the monorepo are as follows:

• site, website or client - General Nuxt3 frontend (universal or static site modes)
• docs - Documentation site
• backend - Backend

Stack

• Requires NodeJS and has been tested on node 20 (node 20+ required)
• Uses a Vue framework, NuxtJS 3
• Styles are written in SCSS, and are concatenated and tree-shaken during compile-time

Static site

• The site workspace can be compiled into a static site, which can then be served as a static resource
• To avoid issues with hoisting npm packages, the site should be run by first navigating to cd packages/site
• This site can be hosted on any resource supporting static files, but may include some services that require a serverless node
• The site itself is served statically, but internal navigation is virtualized in the browser: in other words, the site acts as an SPA when browsed on the client

Local development

To use either workspace, you'll need to create a self-signed certificate (see below) and copy it into the repo.

Generate a self-signed certificate

In order to browse with TLS locally, you'll need a certificate. A self-signed certificate is satisfactory for this purpose. Here's how to set one up.

If you've already done this for a different project, just copy your existing localhost_cert.pem and localhost_key.pem files from ~/.ssh into the root directory of this repo and skip the rest of this step.

• Install mkcert and generate certificate by running the commands below, in this order:

  brew install mkcert nss # replace with another package manager for linux distro, which should also have mkcert available
  
  # at this point, open any https website in Firefox before running the below commands
  cd ~/.ssh
  mkcert -install
  mkcert -key-file localhost_key.pem -cert-file localhost_cert.pem localhost 127.0.0.1
  cat localhost_cert.pem > localhost_fullchain.pem && cat "$(mkcert -CAROOT)/rootCA.pem" >> localhost_fullchain.pem

• Copy the new localhost_cert.pem and localhost_key.pem files to the root directory of this repo

    cd ~/path/to/this/project # navigate to this project on your local machine
    cp -v ~/.ssh/localhost_cert.pem ~/.ssh/localhost_key.pem .

You'll only need to do this once for a valid certificate that lasts 825 days (2.25 years). This certificate can be used across multiple projects. However, after 2 years, mkcert will need to be run again, and the new certificate files will need to be copied to any active project repos once again.

The above tutorial is specifically for MacOS machines with brew installed. For other *nix OS's replace the installation step with your preferred package manager (e.g. apt install mkcert).

Environment variables

Add the following .env file to the repo root

NODE_ENV=development
SERVER_ENV=development

For production deployment, both NODE_ENV and SERVER_ENV should be set to production.

App frontend

To build the frontend:

• Clone this repo
• Make sure Node.js 20 or newer is installed
  • A version 1 or 2 lockfile will not be compatible with this site, so NPM v7 or higher must be used
• Make sure your .env file is set up
• Configure a self-signed certificate for local HTTPS support (see section below)
• Install npm dependencies by running npm ci
• Run npm run dev-site from the repo root to initiate local development
• In production, run npm run build-site first, and then run npm run start-site to initiate the production instance of the application (pm2 can optionally be used to persist this process)
• In either case, the app will let you know which port it's running in the shell's stdout

Static site

To build this static site site:

• Clone this repo
• Make sure Node.js 20 or newer is installed
  • A version 1 or 2 lockfile will not be compatible with this site, so NPM v7 or higher must be used
• Configure a self-signed certificate for local HTTPS support (see next section)
• Install NPM dependencies by running npm ci
• Then, either generate the static site, or run it in local development mode:
  • To build the static site
    • Run npm run generate-site
    • A directory .output/public will be created, which contains the static site output
  • To run in local development mode, for features like hot reload:
    • Run npm run dev
    • The site will be available in real time via a localhost URL

Content

Frontend content is abstracted to a variety of key json files. Currently, the best approach to change content is to clone this repo or edit values in Github. In the future, these json files can be coupled with a headless CMS (ideally one that commits directly into Github and retains the current workflow).

The following is a (non-exhaustive) list of sample key files where content may be found

• packages/site/data/
• packages/site/content/

It's important to maintain abstraction of content, so anything that's content related should be added to json or markdown files, and never within components or other application code files.

Updating dependencies

Please use npm ci in place of npm i when not explicitly upgrading dependencies. npm ci will only install versions of packages provided in the lockfile, leading to more stability.

Always regression test the site if upgrading packages, as they may contain breaking changes.

Commit Messages

Commit messages should use the Conventional Commit format. commitlint has been installed to validate this usage. This means that all commits should be prefixed appropriately with a tag denoting the kind of code being committed.

• feat: A feature, or part of a feature
• fix: A bug fix
• style: A visual or stylistic change only
• chore: An operational task, such as routine maintenance, version control related operations, dependencies, etc.
• refactor: A change to the way the code is implemented, without materially changing the feature
• perf: A change that is made primarily to improve performance
• test: Any changes required to run a specific test or try out a behavior for the purposes of testing
• cleanup: Markup and syntactic cleanup that doesn't affect the code output
• docs: Documentation-related changes
• content: Changes to the project's content, such as copy or media

Style guide

1. All file names will be in kebab-case
2. All component names on import will be PascalCase
3. The grid used is a flexbox style system called Gridlex, its documentation is also available as a readme in this repo
4. Color name variables in SCSS are obtained from this resource

Release Please

• Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects.
• It is currently setup as a github action in this repo
• See documentation on how to use

Initializing Docker container

(optional)

A Docker container configuration is provided for the website. To use it, follow the steps below.

• Download and install Docker CLI
• Navigate to the website cd packages/site
• Run the build command docker build -t site .
• Finally, initialize the container docker run -v "$PWD":/workspace site
• The Dockerfile itself contains some options (commented out) for serving the repo on a local port, after generation

Documentation

See the docs package README.md file for the documentation schema that is used for documenting the zero-core package and soon, the site package.