Set up ESLint

• Install the following VSCode extensions
  • ESLint
  • Volar
• Edit settings.json
  • CTRL+SHIFT+P -> Preferences: Open User Settings (JSON) -- This will open an editor for settings.json.
  • Copy content of settings.json.example into the editor.
  • Disable format-on-save for Volar to avoid formatting conflicts with ESLint.

Set up Javascript CI

• Install typescript yarn add typescript --dev
• Install cypress, use same version as cypress package.json. E.g. yarn add [email protected] --dev
• Add cypress.config.js to your project

const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    specPattern: 'node_modules/glib-web/cypress/e2e',
    defaultBrowser: 'chrome',
    supportFile: 'node_modules/glib-web/cypress/support/e2e.js'
  },
});

• Copy cypress.yml.example to YOUR_PROJECT/.github/workflows/cypress.yml
• Make sure the workflow is compatible with the project
• Run the test
  • Run rails server bin/rails s
  • Execute yarn run cypress run

Run Cypress tests (glib-web-npm)

Cypress tests need a running backend that serves matching test_page/* fixtures. The canonical backend is the gem's dummy-app (glib-web/test/dummy-app), which links the local gem and the local npm package, so the suite exercises your working copies of both — no gem release needed. See doc/TESTING.md for the full picture.

One command (boots the dummy-app, runs Cypress, tears it down) — assumes glib-web is checked out as a sibling of this repo:

yarn test:local:setup   # first run only: bundle/yarn install + db:prepare
yarn test:local         # run the full e2e suite
yarn test:local:open    # interactive Cypress UI
yarn test:local --spec cypress/e2e/glib-web/form.cy.js   # a single spec

If your glib-web checkout isn't a sibling, point at it: GLIB_WEB_DIR=/path/to/glib-web yarn test:local. See scripts/cypress-local.sh for all options.

Do not run bin/vite dev separately while testing — the Rails server compiles Vite internally; a separate dev server causes blank pages.

Best practices

• To prevent circular dependencies between components:
  • It’s okay to use dispatchEvent for upward communication (i.e. child component to ancestors). This fits with how the JS event model works as it already supports event propagation out of the box.
  • For downward communication, don’t use any sort of event/pub-sub mechanism. Always use Vuejs data binding instead.

Markdown line-break contract (richText / markdown display)

Stored markdown uses standard semantics — both the display (Format.markdown) and the editor loader (Format.markdownForEditor) parse with breaks: false:

• A single \n is a soft wrap (renders as a space). Hand-wrapped source (e.g. policy pages) reflows; it no longer renders one <br> per source line.
• An explicit line break is a markdown hard break: trailing double space + \n. This is what htmlToMarkdown saves for a single Enter in the Quill editor. Beware of tooling that strips trailing whitespace — it silently deletes every line break.
• A blank line (\n\n) is a paragraph break; it round-trips through the editor as an explicit empty line. Runs of blank lines cannot be represented and collapse to one.
• Rails views that render TEXTAREA-sourced text through a markdown view must encode newlines themselves (e.g. .gsub(/\r?\n/, " \n")) — a textarea Enter means a visible line break, which markdown's soft-wrap semantics would otherwise swallow.
• The richText editor's blank-line guard and this encoding apply to markdown mode only (produce: 'markdown'); HTML mode stores blank paragraphs verbatim.
• Any component that renders markdown via v-html must put the views-markdown class on the container (see thumbnail/comment/banner). Host apps hang their markdown CSS off that class — without it, Vuetify's reset zeroes paragraph margins and paragraph gaps render flat.
• The views-markdown hook guarantees the LAST block carries no trailing margin (app.scss), so consumer paragraph-spacing rules never pad the container's bottom edge. This holds for both container shapes (markdown.vue's <span>-wrapped content and the bare containers).

Link to local npm during development

• cd glib-web-npm
• yarn install
• yarn link
• cd PROJECT_DIR
• yarn link glib-web
• bin/vite dev

Add custom colors and use its

Add colors

settings.themes = {
  light: {
    dark: false,
    colors: {
      ...
      custom: "#FF5D6D"
    }
  }
};

Use its as styleClasses

# chip group with custom green color
view.chipGroup styleClasses: ['custom']

Clean up to fix strange errors (e.g. tiny-emitter error) when running vite dev

• Stop vite server

• On your glib-web-npm's directory:

  • rm -rf node_modules
  • yarn install

• On your project's directory:

  • rm -rf node_modules
  • yarn link glib-web
  • yarn install
  • bin/vite clobber
  • bin/vite dev

Handling Dependabot Dependency Updates

See doc/dependabot.md.

Prepare for publishing

• Create a PR to the master branch
• Make sure test pass yarn run test
• After approval, merge the PR.

Publish package to npm

• One-off login
  • npm login --registry=https://registry.npmjs.org/glib-web
• Bump version in package.json
• Run npm publish
• Check uploaded version on https://www.npmjs.com i.e. https://www.npmjs.com/package/glib-web
• Commit and push the new package.json