On Magnolia Square

On Magnolia Square website monorepo for frontend and backend.

Prerequisites

Please first have yarn installed on your computer first before starting development. Here is the yarn documentation for installing it.

MacOS - brew specific

If you're using MacOS the brew package corepack is needed. Corepack ships with Node, but zsh does not find this linkage in the shell. Therefore, since we are using brew, corepack can be installed with:

brew install corepack

Brew may error and say that you must remove the symlink for yarn if you used brew to install yarn. Do not fret, run this command:

brew unlink yarn

Then, rerun brew install corepack.

Now, run corepack enable. This will enable corepack globally. Optionally, one can run corepack install --global yarn@stable to install the latest yarn version globally using corepack.

Windows

Install node on Windows and enable corepack. Make sure to run powershell in administrator mode. An error may occur when using yarn, something along the lines of yarn.ps1 cannot be loaded.

To fix this, input this command into the current powershell terminal session:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Setup

In the repository's root directory, run the following commands:

# Install yarn dependencies
yarn

# !! IMPORTANT !!
# Setup husky, a git hook modifier
yarn run postinstall

Development

The frontend and backend directories have .env.example files that must be duplicated and renamed into .env files. Fill in the template with appropriate, legitimate values.

To start development for either backend or frontend, run yarn dev:front or yarn dev:back in the root directory.

Keep in mind that for backend work, one must be logged into the OMS Sanity account to interact with Sanity Studio.

Good Habits

Commits

Commits in this repository follow Conventional Commits, with some minor changes fit for our project. Here's a ChatGPT chat about what they are.

When making a commit, one must specify the affected package (the scope) next to the type:

• f(rontend)
• b(ackend)

The third type is null, i.e. something that is not a package specific change. Here is an example of what this looks like:

# (b) indicates a backend commit
git commit -m "refactor(b): remove whitespace"

# (f) indicates a frontend commit
git commit -m "fix(f): Component.svelte state logic"

# null type
git commit -m "chore: bump yarn version"

Code Attribution

Proper code attribution is to be followed.

Branching

The main branch is dev. The production branch is main. The deployment pipeline is as follows:

dev to staging then finally to main.

This pipeline is enforced by the enforcer.yml GitHub action.

Staging is a pre-release branch. This is where we test the dataset against any new releasable changes from dev. It is not publicly viewable.

Technical Specifications

Yarn

Our package manager is the latest version of yarn. The version is using the command yarn set version stable, which, during version updates, is executed in the root directory. Since this is a monorepo, yarn is also used as the project management tool.

In the package.json folder, you can find the workspaces field, which defines which folders yarn will look and install modules for.

With that being said, Vite does not yet support Yarn pnp, and therefore in the .yarnrc.yml file in the root directory, nodeLinker: "node-modules" line is appended. In the future, we may remove this in case of ghost-dependency creep, or if Vite begins support for pnp.

What is run -T (command)?

It's used to share commands between workspaces. Since a project like frontend does not have any dependencies inside (all of the dependencies are in the root dir), we must use run -T (command) to access the correct command. In this case, its either vite or sanity or any other that requires use like playwright.

VS Code

Below are VS Code extensions used in this project.

• Svelte for VS Code
• Sanity.io GROQ extension
• Code Spell Checker (by Street Side Software)
• Codeium
• Prettier

Development

Useful Commands

Convert .ndjson to .json

Required software: jq

jq --slurp '.' in.json > out.json

Retrieved from: https://stackoverflow.com/questions/45456414/convert-json-lines-to-json-array-using-jq

Route Enforcement

To enforce categories and routes, we are using src/params to enforce only certain route categories. This is an example of the Route Matching and Route Rest Parameters of SvelteKit.

Page Server Loading

Load Server Page for Sanity

Deployment

CI requires unit tests and perhaps integration tests if you could secure a development key. This comes with managing the secret on GitHub, though.

The frontend is deployed to Cloudflare pages. The backend is deployed via the Sanity CLI deploy command. The frontend requires the environment variables to be injected at build time in order to build and deploy successfully. These can be accessed in either Cloudflare page's or Vercel's appropriate deploy configuration settings. Make sure all of the .env.example fields are used in the deployment environment.

Useful Links

Build

• Yarn workspace tutorial and cheatsheet
• Using yarn workspaces to create a monorepo

Testing

• SvelteKit testing with Vitest
• Vite Testing Data Driven Tests Parameterization

GitHub Actions

• Filter Pattern Cheat Sheet
• Vitest Coverage
• Vitest Workspace
• Add formatting and styles to JS console log
• Vitest - Vitest hangs tests, close timed out after 1000ms

GitHub

• Git Merge

Actions

• act - Local GitHub action runner
• Prevent File Change
• Auto Assign
• Require Labels
• Google Sheet
• Building a CI/CD environment with eslint and prettier
• Integrating and Enforcing ESLint and Prettier with Husky

Sanity

• Sanity and Algolia
• Pagination with Groq

Troubleshooting

Vitest

--no-threads command not found

• It was converted to --pool forks --poolOptions.forks.singleFork

Design

• Magnolia in Shanghai
• Social Icons SVGs

Prettier

• Prettier prose-wrap
• Markdown callout for GitHub Prettier