@tacc/core-styles

TACC Core Styles

The shared styles for TACC WMA Workspace Portals & Websites

Related Repositories

• Core CMS, the base CMS code for TACC WMA CMS Websites
• Core Portal, the base Portal code for TACC WMA CMS Websites

Local Development Setup

Prequisites for Running

• Nodejs 15.x

External Project Usage

CLI

Usage: core-styles [options] [command]

Options:
  -V, --version      output the version number
  -h, --help         display help for command

Commands:
  build [options]    build stylesheets with TACC standard process:
  - "post-css" plugins
  - custom input path
  - custom output path
  - custom configs
  - prepend build id

  help [command]     display help for command

Build Command

Usage: core-styles build [options]

build stylesheets with TACC standard process:
- "post-css" plugins
- custom input path
- custom output path
- custom configs
- prepend build id

Options:
  -i, --input <path>               parse source at which path¹
  -o, --output <path>              output CSS files to which path¹
  -v, --verbose                    print more info during build process
  -c, --custom-configs <paths...>  extend base config with YAML files²³
  -b, --build-id <identifier>      any value to identify the build (default: version of app)
  -m, --base-mirror-dir <path>     if input folder structure is mirrored, this path is not⁴
  -h, --help                       display help for command

Notes:
  ¹ Folder structure of "--input-dir" mirrored in "--output-dir" i.e.

    given input
    - "input_dir/x.css"
    - "input_dir/sub_dir_a/y.css"
    - "input_dir"
    - "input_dir/**/*"

    expect output
    - "output_dir/x.css"
    - "output_dir/sub_dir_a/y.css"
    - "output_dir/..." (all files from input not in sub-directories)
    - "output_dir/.../..." (all files from input as nested)

  ² The file formats are like ".postcssrc.yml" from
    https://github.com/postcss/postcss-load-config#postcssrc

  ³ The first file is merged on top of the base config.
    Each successive file overwrites the file before it.

  ⁴ Given '-i "a/b*" -o "x/" -m "a/"' output is "x/b/...".
    Given '-i "a/b*" -o "x/" -m "a/b/"' output is "x/...".
    Given '-i "a/b*" -o "x/" -m "not-a/"' output is "x/abs-path-to-input/...".

Module

1. Install the package with any package manager e.g.:

• npm install @tacc/core-styles
• yarn add @tacc/core-styles

1. Import stylesheets of either type:
   • pre-compiled, from /dist
   • source files, from /src/lib/_imports

Build Script

const buildStylesheets = require('core-styles').buildStylesheets;

buildStylesheets(
  // Parse CSS files from which directory (required)
  `path/to/your/css/src`,
  // Output CSS files to which directory (required)
  `path/to/put/css/output`,
  {
    // List of YAML config files (optional)
    // (The first file is merged on top of the base config.)
    // (Each successive file overwrites the file before it.)
    // SEE: https://github.com/postcss/postcss-load-config#postcssrc
    customConfigs: [
      // The "base" config is `/.postcssrc.base.yml`
      `path/to/custom/configthat/extends/base/.postcssrc.yml`,
      `path/to/custom/config/that/extends/above/.postcssrc.yml`,
    ],
    // Print more info from build log (optional, default: false)
    verbose: true,
    // Print version of this software (optional, default: false)
    version: true,
    // Any value to help identify the build (optional, default: app version)
    buildId: process.env.npm_package_version + someUniqueId,
  }
);

Local Development Setup

Code Configuration

Code configuration happens in repos that use these styles.

Previewing Built Demo

1. Build stylesheets and build static demo:

   npm run build
   

2. Run the static demo:

   npx serve demo
   

   ^{Live reloads on demo file change, but not source file change.}

3. Open the web interface. The build command will output the URL (and may even open it for you).

Previewing During Development

Run each of these commands in its own terminal.

1. Build stylesheets and re-build on change:

   npm run build:watch
   

2. Run the auto-refresh demo:

   npm start
   

^{Source file change causes two demo refreshes. The second reload will show changes.}

Source Files

If you changes files in a src/lib/ directory, you may need to follow some of these steps.

Quick Start

1. (optional) Make changes to /src/lib files.
2. Build the styles: npm run build:css
3. Build and preview the styles: npm start
4. (to debug) Review respective /dist or /demo files' content.

How to Just Build Stylesheets

You can build stylesheets from source files in src/lib directory to compiled files in dist directory.

1. Build stylesheets:

   npm run build:css
   

   or, for custom build id:

   npm run build:css -- --build-id="..."
   

Testing

Plugin testing is done manually. Run npm run test, then review output in /dist/_tests.css, to ensure plugins are working correctly.

Style testing is done manually. Run npm start, then review output at web interface, to ensure styles are rendering correctly.

Production Deployment

The Core Styles are not deployed alone yet. ¹

For now, the stylesheets are acquired or accessed by other repositories.

Repo	Usage
Core CMS	via CLI installed on test branch
Core CMS Pattern Library	not accessing styles yet ¹

_{¹ A repo that is, or will be, in Core CMS Pattern Library should load these styles and build a pattern library.}

Contributing

Development Workflow

We use a modifed version of GitFlow as our development workflow. Our development site (accessible behind the TACC Network) is always up-to-date with main, while the production site is built to a hashed commit tag.

• Feature branches contain major updates, bug fixes, and hot fixes with respective branch prefixes:
  • task/ for features and updates
  • bug/ for bugfixes
  • fix/ for hotfixes

Best Practices

Sign your commits (see this link for help)

Publishing Workflow

Only authorized team members may publish.

1. (one time) Login to npm i.e. npm login.
2. Create new branch for version bump.
3. Update CHANGELOG.md.
4. Update version via npm version N.N.N.
5. Commit, push, PR, review, merge.
6. Create release and tag on GitHub.
7. Publish to NPM via npm publish --access public.

Notice: Project build will automatically occur before publish.

Resources

• Learn Markdown

Changelog

[0.13.0] - 2023-05-08: Retire env()-based Themes (for Core-CMS v3.9)

Changed

• feat!: retire env()-based themes (Core-CMS v3.9) (#164)