Develop with Client Code Simultaneously

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}

Tip

If you do not want to push work to test it, then try https://github.com/wclr/yalc instead.

Steps

First, In Core-Styles Clone

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

Then, In Client Repo Clone

Note which version of Core-Styles is installed e.g.
npm list @tacc/core-styles
_{Remember this. You will use it "To Revert Changes".}
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.

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.}

Collect static assets e.g.
docker exec -it core_cms sh -c "python manage.py collectstatic --no-input"
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:

Install Core-Styles as it was before your install e.g.
npm install --save @tacc/core-styles@2.17.0
Rebuild stylesheets (and collect the static files).
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)}

clone tup-ui or Core-Styles
checkout branch that is appropriate for your development (or testing)
navigate to Core Styles clone
_{e.g. Core-Styles}
commit development so you can push
git push so client can access it
navigate to Core CMS clone
_{e.g. cd ../Core-CMS}
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)}

clone tup-ui or Core-Styles
checkout branch that is appropriate for your development (or testing)
navigate to Core Styles clone
_{e.g. cd tup-ui/libs/core-styles, Core-Styles}
npm ci so you can build
npm run build so you have a dist
npm run pack so you have a proper package to install
navigate to Core CMS clone
_{e.g. cd ../Core-CMS}
npm ci so you can build
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}
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)}

Clone template repository https://github.com/wesleyboar/Core-Workspace.
Follow the steps in its Readme.

Or set up your own NPM workspace _{(click to toggle steps)}

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.
Add a package.json into the workspace directory.

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"
  ],

In the workspace directory, run npm ci.
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.

(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)}

clone tup-ui or Core-Styles
checkout branch that is appropriate for your development (or testing)
navigate to Core Styles clone
_{e.g. cd tup-ui/libs/core-styles, cd Core-Styles}
npm ci so you can build
npm run build so you have a dist
navigate to Core CMS clone
_{e.g. cd ../Core-CMS}
npm ci so you can build
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")}
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)}

clone tup-ui or Core-Styles
checkout branch that is appropriate for your development (or testing)
navigate to Core Styles clone
_{e.g. cd tup-ui/libs/core-styles, cd Core-Styles}
npm ci so you can build/pack
navigate to Core CMS clone
_{e.g. cd ../Core-CMS}
npm ci so you can build
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")}
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)}

Test a change very well.
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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Develop with Client Code Simultaneously

Overview

Steps

First, In Core-Styles Clone

Then, In Client Repo Clone

Core-CMS

Client of Core-CMS

Different Client of Core-Styles

Optionally, Revert Changes In Client Repo Clone

Archive

☆. ✅ `npm install` from Core-Styles

A. ✅ `npm pack` in Core-Styles

B. ✅ Using NPM Workspaces and `npx link`

C. ❌ Using `npm link`

D. ❌ Using `npx link`

E. 👎 Using @tacc/core-styles

F. 💡 Return Core-Styles to its own repo

G. ❓ Investigate Git Subtree

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Develop with Client Code Simultaneously

Overview

Steps

First, In Core-Styles Clone

Then, In Client Repo Clone

Core-CMS

Client of Core-CMS

Different Client of Core-Styles

Optionally, Revert Changes In Client Repo Clone

Archive

☆. ✅ npm install from Core-Styles

A. ✅ npm pack in Core-Styles

B. ✅ Using NPM Workspaces and npx link

C. ❌ Using npm link

D. ❌ Using npx link

E. 👎 Using @tacc/core-styles

F. 💡 Return Core-Styles to its own repo

G. ❓ Investigate Git Subtree

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

☆. ✅ `npm install` from Core-Styles

A. ✅ `npm pack` in Core-Styles

B. ✅ Using NPM Workspaces and `npx link`

C. ❌ Using `npm link`

D. ❌ Using `npx link`