Skip to content

Develop with Client Code Simultaneously

Jump to bottom
Wesley B edited this page Mar 1, 2024 · 6 revisions

Overview

Within a client repo (e.g. a CMS*) install Core-Styles at a specific branch (or commit or tag).

* Core-CMS or Core-CMS-Custom or TUP-UI or Core-CMS-Resources

Steps

First, In Core-Styles Clone

  1. In a branch appropriate for your development, commit and push changes.

Then, In Client Repo Clone

  1. Note which version of Core-Styles is installed e.g.
    npm list @tacc/core-styles
    Remember this. You will use it "To Revert Changes".
  2. Install Core-Styles at your development branch e.g.
    npm install --save TACC/Core-Styles#name_of_your_branch

Core-CMS

3. Build CMS stylesheets. 4. Collect CMS static assets. 5. Open CMS and test.

Important
Develop with docker-compose -f ./docker-compose.dev.yml up, not make start.

  1. Build stylesheets e.g.
    for this target CMS run this command in Core-CMS
    Core-CMS npm run build:css --build-id="$(git describe --always)"
    Core-CMS-Resources npm run build:css --build-id="$(git describe --always)" --project="__CUSTOM_CMS_DIR_NAME__"
    Where __CUSTOM_CMS_DIR_NAME__ is the name of the custom CMS directory in Core-CMS-Custom.
  2. Collect static assets e.g.
    docker exec -it core_cms sh -c "python manage.py collectstatic --no-input"
  3. Open your instance of the CMS and test the change.
    You may need to clear browser cache.

Client of Core-CMS

Update Dockerfile to use Core-CMS image that has Core-Styles version you want.
for this target CMS follow these instructions
TUP-UI CMS https://github.com/TACC/Core-CMS/wiki/Locally-Develop-CMS-and-TUP-CMS
Core-CMS-Custom undocumented

Different Client of Core-Styles

Refer to client repo documentation.

Optionally, Revert Changes In Client Repo Clone

To undo your testing of Core-Styles in a client repo:

  1. Install Core-Styles as it was before your install e.g.
    npm install --save @tacc/core-styles@2.17.0
  2. Rebuild stylesheets (and collect the static files).
  3. Undo any changes to package.json or package-lock.json that you did not intend to commit.

Archive

Important

These unused steps were written for Core-CMS development, at a time when Core-Styles could have remained a lib/ in tup-ui, but the knowledge can be applied to other client repositories.

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 ...Core-Styles@v0.11.0

⚠️ 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.

Clone this wiki locally