Skip to content

Locally Develop CMS and Styles

Jump to bottom
Wesley B edited this page Nov 5, 2022 · 27 revisions

Prerequisites

  1. Your Core-CMS clone must be at or past the HEAD of branch task/fp-1499-cms-pattern-library--general-fix-for-import-paths.
  2. Your tup-ui clone must be at or past the HEAD of branch task/fp-1499-cms-pattern-library--general-fix-for-import-paths.

Options

A. ✅ Using npm pack

Pack Core-Styles locally and tell Core-CMS to use local package (click to toggle steps)
  1. clone tup-ui or Core-Styles
  2. checkout branch that is appropriate for your development (or testing)
  3. navigate to Core Styles clone
    e.g. cd tup-ui/libs/core-styles, Core-Styles
  4. npm ci so you can build
  5. npm run build so you have a dist
  6. npm run pack so you have a proper package to install
  7. navigate to Core CMS clone
    e.g. cd ../Core-CMS
  8. npm ci so you can build
  9. npm install --no-save path-to/core-styles/the-tarball.tgz
    so app can load @tacc/core-styles from local package
    e.g. npm install --no-save ../tup-ui/libs/core-styles/tacc-core-styles-0.8.0-beta.tgz
  10. npm run build --project=core-cms
    (requires a project e.g. core-cms, frontera-cms, texascale-org)

B. ✅ Using NPM Workspaces and npx link

Either use a template repository (click to toggle steps)
  1. Clone template repository https://github.com/wesleyboar/Core-Workspace.
  2. Follow the steps in its Readme.
Or set up your own NPM workspace (click to toggle steps)

  1. Create a directory that has a clone of the Core-CMS and tup-ui or Core-Styles repos.

    • If they are already in such a parent directory, you may continue these steps from that directory.

  2. Add a package.json into the workspace directory.

  3. In package.json, add workspaces object of package paths. (click to toggle example)

    with tup-ui:

      "workspaces": [
    "Core-CMS",
    "tup-ui/libs/core-styles"
  ],

    with Core-Styles:

      "workspaces": [
    "Core-CMS",
    "Core-Styles"
  ],

  4. In the workspace directory, run npm ci.

  5. In the Core-CMS directory, run npx link --no-save ../tup-ui/libs/core-styles.

    • Afterward, development within Core-CMS should automatically use Core Styles from your local clone.
  6. (Optional) You may add convenience scripts within the package.json. (click to toggle example)

    with tup-ui:

       "scripts": {
     "core-cms:": "cd core-cms &&",
     "core-cms:demo": "npm run core-styles: npm run build:css --project=$npm_config_project && npm run core-cms: npm run build --project=$npm_config_project",
     "core-styles:": "cd tup-ui/libs/core-styles &&",
     "core-styles:demo": "npm run core-styles: npm run build:css && npm run core-styles: npm run start",
     "postinstall": "npm run core-cms: npx link ../tup-ui/libs/core-styles"
   },

    with Core-Styles:

       "scripts": {
     "core-cms:": "cd core-cms &&",
     "core-cms:demo": "npm run core-styles: npm run build:css --project=$npm_config_project && npm run core-cms: npm run build --project=$npm_config_project",
     "core-styles:": "cd core-styles &&",
     "core-styles:demo": "npm run core-styles: npm run build:css && npm run core-styles: npm run start",
     "postinstall": "npm run core-cms: npx link ../core-styles"
   },

C. ❌ Using npm link

Tell Core CMS to use your local Core Styles (via NPM) (click to toggle steps)

  1. clone tup-ui or Core-Styles

  2. checkout branch that is appropriate for your development (or testing)

  3. navigate to Core Styles clone
    e.g. cd tup-ui/libs/core-styles, cd Core-Styles

  4. npm ci so you can build

  5. npm run build so you have a dist

  6. navigate to Core CMS clone
    e.g. cd ../Core-CMS

  7. npm ci so you can build

  8. npm link path-to/core-styles so app can load @tacc/core-styles from local clone
    e.g. npx link --no-save ../tup-ui/libs/core-styles, npx link --no-save ../Core-Styles
    (ignore symlink error about cli.js, or see "Known Issues")

  9. npm run build --project=core-cms
    (requires a project e.g. core-cms, frontera-cms, texascale-org)

    ❌ This currently fails (at npm run build:css) with an error about postcss-cli being unavailable.

    ❌ Using npm link has 4 "footgun" problems.

    ❌ Running npm run build:demo --project=core-cms causes Error: Fractal themes must inherit from the base Theme class.

    💡 The problem might be with de-duping.

D. ❌ Using npx link

Tell Core-CMS to use your local Core-Styles (via third-party Node package) (click to toggle steps)

  1. clone tup-ui or Core-Styles

  2. checkout branch that is appropriate for your development (or testing)

  3. navigate to Core Styles clone
    e.g. cd tup-ui/libs/core-styles, cd Core-Styles

  4. npm ci so you can build/pack

  5. navigate to Core CMS clone
    e.g. cd ../Core-CMS

  6. npm ci so you can build

  7. npx link path-to/core-styles so app can load @tacc/core-styles from local clone
    e.g. npx link --no-save ../tup-ui/libs/core-styles, npx link --no-save ../Core-Styles
    (ignore symlink error about cli.js, or see "Known Issues")

  8. npm run build --project=core-cms
    (requires a project e.g. core-cms, frontera-cms, texascale-org)

    ❌ This currently fails (at npm run build:demo) with Error: Fractal themes must inherit from the base Theme class.

    💡 The problem might be with de-duping. See frctl/fractal#821 comment.

    ℹ️ Using npx link with NPM workspaces is successful.

E. 👎 Using @tacc/core-styles

Publish version to NPM just for peer testing (click to toggle steps)
  1. Test a change very well.
  2. Publish a new version of @tacc/core-styles.

⚠️ We should not publish versions just for testing!

The following ideas might affect tup-ui.

F. 💡 Return Core-Styles to its own repo

Use Core-Styles standalone repo (click to toggle steps)

Because core-styles being a sub-directory makes it tricky for clients to pin, we could move core-styles to its own repo again, then all clients could just test core-styles by installing it off the relevant branch.

😕 Seems to defeat the purpose of having a monorepo.
😕 Will not work if CMS relies on Core-Styles dist/ (not just source/).¹

¹ Because dist/ is not committed to Git, thus requires build step to create, which requires any other solution.

G. ❓ Investigate Git Subtree

Use the Git alternative to Git submodule (click to toggle steps)

The git subtree feature allows cloning just a sub-directory of a repo.

⚠️ I do not yet know how it can help nor how to use it. — Wes B.

TACC ACI WMA Core-CMS Project Documentation

Clone this wiki locally