Skip to content

Locally Develop CMS and Styles

Jump to bottom
Wesley B edited this page Oct 17, 2023 · 27 revisions

Overview

Within a CMS (Core, Custom, or TUP), via the container, install Core-Styles at a specific branch (or commit or tag).

Steps

  1. Clone Core-Styles (if you haven't already).
  2. Navigate to your Core Styles clone e.g. cd Core-Styles.
  3. Checkout branch that is appropriate for your development (or testing).
  4. Commit any changes.
  5. Push those changes e.g. git push.
  6. Navigate to CMS clone e.g. cd ../Core-CMS.
  7. Enter the CMS container e.g.
    • docker exec -it core_cms /bin/bash
    • docker exec -it tup_cms /bin/bash
  8. (within the container)
    Install Core-Styles at your development branch e.g.
    • npm install --save-dev TACC/Core-Styles#task/wp-123-describe-task
    • npm install --save-dev TACC/Core-Styles#6229442
    • npm install --save-dev TACC/[email protected]
  9. (within the container)
    Rebuild stylesheets and collect static files:
    • npm run build:css && python manage.py collectstatic --no-input
    • npm run build:css --project="tup_cms" && python manage.py collectstatic --no-input
    • npm run build:css --project="ecep_cms" && python manage.py collectstatic --no-input
  10. Open your instance of the CMS (https://localshost:8000/) and test the change.
    • You may need to clear browser cache.

Archive

Outdated Instructions

☆. ✅ npm install from Core-Styles

Pin Core-Styles NPM install in Core-CMS at use branch, commit, tag (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. Core-Styles
  4. commit development so you can push
  5. git push so client can access it
  6. navigate to Core CMS clone
    e.g. cd ../Core-CMS
  7. npm install --save-dev github:TACC/Core-Styles...
    so app can load @tacc/core-styles at specific state
    e.g. npm ...Core-Styles#6229442, npm ...Core-Styles#task/fp-123-describe-task, npm [email protected]

⚠️ This solution is less obvious for tup-ui. It can be done via obtuse command (arcane repair), git submodules (team dislike), or third-party service (unreliable maintenance) (source).

A. ✅ npm pack in Core-Styles

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