@tacc/core-styles

TACC Core Styles

The shared styles for TACC WMA Workspace Portals & Websites

Known Clients

• Core CMS, the base CMS code for TACC WMA CMS Websites
• Core Portal, the base Portal code for TACC WMA CMS Websites
• TUP UI, the client code for TACC User Portal

Table of Contents

• External Project Usage
• Local Development Setup
• Testing
• Deployment
• Contributing

External Project Usage

Install This Package

1. Installwith any package manager e.g.:

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

2. Import stylesheets of either type:

   • pre-compiled, from /dist
   • source files, from /src/lib/_imports

Build from Source

Via Your Environment's PostCSS

Please review the plugins expected.

Via Core-Styles API

JavaScript

require('core-styles').buildStylesheets

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/config/that/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,
  }
);

CLI

core-styles

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

core-styles build

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/...".

Local Development Setup

Prequisites for Running

• Nodejs 15.x

Quick Start

1. (initially) Install dependencies:
   npm ci

2. (optional) Make changes to /src/lib files.

3. Build the styles*:
   npm run build:css

4. Build and preview the styles*:
   npm start

5. (to debug) Review output in respective /dist or /demo files.*

_{* Stylesheets are built from source files in src/lib directory to compiled files in dist directory.}

Preview After Development

1. Build stylesheets and build static demo:

   npm run build
   

2. Run the static demo:

   npx serve demo
   

   ^{Web page will live-reload on demo build, but not on change of source files.}

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

Preview During Development

Run each of these commands in its own terminal.

1. Build stylesheets and re-build on change:

   npm run watch
   

2. Run the auto-refresh demo:

   npm run start
   

^{Web page will live-reload twice on change of source files. The second reload will show changes.}

Build Options

Regular CSS Build

npm run build:css

Custom Build ID

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

Testing

All testing is done manually.

Deployment

Production Deployment

The Core Styles are not independently deployed.

Currently, the demo is served by Core CMS (since v3.9.0).

Later, the demo may be deployed indpendently and core-styles.….css served from a CDN.

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. Update dist via npm run build:css --build-id=vN.N.N.
6. Commit, push, PR, review, merge.
7. Create release and tag on GitHub.
8. Publish to NPM via npm publish --access public.

Notice: Project build will automatically occur before publish.

Resources

• Learn Markdown
• Research & Development

Changelog

[2.0.1] - 2023-03-01: Add Missing Way to Use Theme from Dist

Fixed

• feat: build has-dark-logo–themed stylesheets (#134)