Skip to content

Latest commit

 

History

History
415 lines (320 loc) · 14.3 KB

README.md

File metadata and controls

415 lines (320 loc) · 14.3 KB

RoundingWell logo

CircleCI Coverage Status Cypress.io tests

Getting Started: Frontend

Documentation for the RoundingWell frontend can be found within README.md files throughout this repo.

Dependencies & Installation

We use npm for our package manager

Node

You will need Node.js. It is recommended that devs install nvm the node version manager. NVM allows you to change node versions on the fly.

Once NVM is installed, activate the right Node version with:

$ nvm use

Installing Project Dependencies

With existing Git read access to RoundingWell/pkg-icons, install with:

$ npm ci

Agent skills

After installing dependencies, explicitly expose the installed Marionette skill:

$ npm run setup:agents

This offline step checks that the installed SKILL.md exists, then creates ignored, relative directory symlinks at .agents/skills/marionette and .claude/skills/marionette, pointing directly to node_modules/marionette/skills/marionette. Repeating setup preserves those links. Conflicting files, directories, or links fail without replacing them; move the conflicting entry aside before retrying. Symlink creation must be supported by your OS and checkout permissions.

Setup is optional for ordinary app development and never runs during npm ci or app startup. It checks source presence and link safety, leaving version and documentation verification to the installed upstream skill. Framework guidance stays upstream and follows the installed dependency. The upstream plugin's version is independent of the framework pin in package.json; this setup does not install/update plugins or configure MCP.

Creating links does not prove a client discovered or used the skill:

  • In Codex, open this checkout, find the project skill in /skills, and invoke $marionette. Restart the session if it is missing. The project .agents/skills location supports symlinked skill folders.
  • In Claude Code, open this checkout, find /marionette in the skill menu, and invoke it. Its project .claude/skills location supports symlinked folders.
  • Cursor and supported Copilot surfaces also recognize these project locations. Verify their skill selector and symlink support for the client version you use.
  • Other clients must support these project locations and directory symlinks. Verify their skill selector/invocation independently; otherwise read the installed SKILL.md directly as described in AGENTS.md.

For an actual local lookup, run node .agents/skills/marionette/scripts/docs.mjs --page docs/tooling.md from the repo root and confirm the reported package version/revision. If a plugin and the project skill both appear, choose the project entry to verify this bootstrap. Client trust, disabled skills, remote sessions without dependencies, and plugin permission prompts can still prevent loading. Handle those in the client; setup never changes authentication, permissions, or global settings.

Releasing

Releases are tag-based. CircleCI publishes a release artifact from version tags, and deploys consume that artifact. Deployment steps for local and CircleCI runs are documented in the deployment runbook.

Allowed release sources:

  • local branch develop
  • local branch matching release/*

Release command:

$ npm run release

Dry run (runs checks and prints the next tag without creating/pushing):

$ npm run release -- --dry-run

Tag format:

  • vYYMMDD.N (UTC date, sequence starts at 1)
  • Example: v260212.1

Tag immutability:

  • release tags are treated as immutable
  • existing remote release tags are never reused or moved

Release behavior changes:

  • release no longer creates/pushes release branches
  • release no longer commits dist

Development

All development work should branch off of and PR into the develop branch.

Setting Up Your Development Environment

Backend Setup

To develop against a remote AWS dev organization:

  1. Deploy your backend organization (replace john with your organization slug):

    bin/console deploy:dev john
  2. After your first login, prepare a clinician account:

    bin/remote <organization> console clinician:prepare <email>

    For example, if your organization is john and your email is john.doe@roundingwell.com:

    bin/remote john console clinician:prepare john.doe@roundingwell.com

Frontend Setup

On an interactive npm run dev, a missing .env is created from prompts. The setup asks for your lowercase dev organization slug, whether to use a local or remote backend, and defaults DEPLOY_AWS_PROFILE and DEPLOY_STAGE to dev (press Enter to accept, or type another value):

DEPLOY_AWS_PROFILE=dev
DEPLOY_STAGE=dev
DEPLOY_ORGANIZATION=john
VITE_DEV_API_URL=https://john.roundingwell.dev

Note: Replace john with your organization slug.

Choose remote for the dev organization URL shown above. Choose local to omit VITE_DEV_API_URL, which makes the Vite dev server use http://localhost:8080 and serve local status icons.

An existing .env is never overwritten, and non-interactive runs (CI, piped commands) skip creation with a notice and start Vite with its defaults. To set up .env without starting the server, run node scripts/create-env.js.

Deploying the Frontend to a Dev Organization

With the repo .env file present and AWS SSO credentials available, replace <your-org> with your organization slug:

npm run deploy:dev -- --stage=dev --organization=<your-org>

See the deployment runbook for AWS profile setup, .env defaults, and CircleCI deployment steps.

Running the Development Server

There are two npm commands most useful for development:

Use this for local development with the Vite dev server against your remote care-ops-backend environment:

$ npm run dev

Use this to develop in the Cypress GUI:

$ npm test

Occasionally the Vite server does not release the port, so development in either environment will use the wrong port and fail. To fix this, try:

$ npm stop

If this doesn't work try turning your computer off and then on again 😜

Important Dependencies

Follow AGENTS.md and the src/js guide for local ownership, View, and DOM conventions. The Marionette application context records the installed integrations and how to retrieve version-matched framework API docs with Marionette's upstream marionette plugin and skill. See the agent tooling guide for setup.

  • Backbone.Store A small but important library that ensures there is only a single instance of a model in memory. It is used for both server models and to sync state models across applications.
const MyModel = Backbone.Model.extend({...});

const MyUniqueModel = Backbone.Store(MyModel);

const myUniqueModel = new MyUniqueModel({ id: '1', foo: 'bar' });
const sameModel = new MyUniqueModel({ id: '1' });
sameModel.get('foo') === 'bar'; // true

const nonUnique = new MyModel({ id: '1' });
nonUnique.get('foo') === 'bar'; // false
  • Store.js A library for accessing localstorage across browsers

Icons 🧰

Add app icons to root icons.json, then build normally:

{ "far": ["check"], "fas": ["check"], "fal": ["acorn"], "fat": [] }
{{far "check"}}
{{fal "acorn"}}
flowchart LR
  A["pkg-icons 🔒"] --> B["App icons.json → inline SVG"]
Loading

npm ci uses your existing Git read access to the private pkg-icons toolbox. No App setup is needed locally. For SSH-only Git auth, configure this checkout once:

git config --local url."git@github.com:RoundingWell/pkg-icons.git".insteadOf \
  https://github.com/RoundingWell/pkg-icons.git
npm ci

CI uses HTTPS with node scripts/install-icons-ci.mjs. A small, scripts-disabled public bootstrap loads Octokit for GitHub App authentication. CircleCI supplies PKG_ICONS_APP_CLIENT_ID, PKG_ICONS_APP_INSTALLATION_ID and PKG_ICONS_APP_PRIVATE_KEY_BASE64. Encode the downloaded RSA PEM on macOS:

base64 < /path/to/app-private-key.pem | tr -d '\r\n' | pbcopy

Save the clipboard as PKG_ICONS_APP_PRIVATE_KEY_BASE64 in CircleCI. The bootstrap decodes it in memory and mints a short-lived pkg-icons-only Contents: read token. Invalid credentials fail before installation; keys never reach install hooks.

This app pins an immutable @roundingwell/icons revision in package-lock.json. That revision currently contains Font Awesome 7.2.0 (7.2.0-rw.0). Only selected manifest icons enter the browser bundle; ordinary installs make no FontAwesome requests. Catalog, provenance and update instructions live in the toolbox README.

Templating and Styles

Handlebars templates and stylesheets should be imported directly into the modules they're used. Handlebars can also be made inline using the ``hbs```` template literal

import CompiledTemplate from './template-file.hbs';
import 'some-styles.scss';
const OtherTemplate = hbs`
  <div class="other-template">
    This multi-line template will be precompiled during the build process.
  </div>
`;

Feature Flags

Feature Flags are intended to protect users from new code that isn't fully baked or to allow for gradual rollout. Right now we have one flag for development purposes.

if (_DEVELOP_) {
  // new code
}

Using Feature Flags

Flags are best used such that a minimal amount of changes are made when the flag is being removed.

// Bad
function foo() {
  if (flag) {
    doNew();
  } else {
    doOld();
  }
}

// Good
function foo() {
  if (!flag) {
    doOld();
    return;
  }
  doNew();
}

It also may be better to duplicate larger areas of code for fewer easier to remove flags.

// Bad
function foo() {
  if (flag) foo();
  bar();
  baz();
  if (!flag) bazinga();
  quxx();
}

// Good
function foo() {
  if (!flag) {
    bar();
    baz();
    bazinga();
    quxx();
    return;
  }

  foo();
  bar();
  baz();
  quxx();
}

Code Standards

Outside of linting there are some recommendations for code standards that will help in long term maintenance.

  • SASS follows a general BEM format. Ideally do not make deep elements, but start a new block if additional descriptors are needed.
  • Favor object composition over class inheritance
  • Within reason functions should ideally accomplish one task in less than 10 lines unless logically trivial. If it is getting to big, break up the function.
  • Similarly modules should ideally get no larger than 300 lines or so. This is a general guideline and not a rule.
  • Use only .js- prefixed selectors if at all possible from the code. Do not use style classes, ids, or tagnames if it can be avoided.
  • Define template element selectors in a View's ui hash and access them with getUI rather than querying selectors from View methods.
  • The view should have say over only the DOM inside its own template or in the case of a CollectionView sometimes its direct children. Avoid allowing deep reaching within the DOM or anything external changing the DOM besides the view itself.
  • Anything AJAX should happen within the entities service only.
  • Generally it is better to store state on a state model than to append a property to an instance.
  • Events and handlers should be named verb:subject or context:verb:subject based on what happened not what will happen ie:
triggers: {
  'click .js-button1': 'show:modal' // bad
  'click .js-button2': 'click:button2' // good
},
childViewTriggers: {
  'click:button': 'button:clicked', // bad
  'click:button': 'listItem:click:button' //good
},
onShowModal() {
  console.log('The naming of this handler suggest a modal was just shown');
},
onClickButton2() {
  this.showModal(); // It's ok for a handler to simply call a single action
}

Use guards to handle the exception on functions when possible ie:

// Good
doFoo(options) {
  if (!options.bar) {
    this.doSomethingElse();
    return;
  }

  return 'Foo:' + options.bar;
}

// Bad
doFoo(options) {
  if (options.bar) {
    return 'Foo:' + options.bar
  } else {
    this.doSomethingElse()
  }
}

An Open Source Culture

It is our intention to open source by default. Ideally any generic solution can be extracted, well documented, and tested. Open sourcing encourages better code, collaboration with outside developers, and potentially free battle-testing, bugfixes and features from the public.

Our Libraries

Libraries for public consumption are licensed with the MIT License.

Currently our OS projects are available mainly at https://github.com/RoundingWellOS

Each project contains its own documentation for contributions.

Other Libraries

Additionally we actively encourage contributing to other projects. Don't know where to start? Look at documentation or tests for any of the libraries we use.