The university web framework. This repository holds the source files of core Compass assets.
You can include Compass as an NPM dependency in your next project, allowing you to pull in just the HTML, JS, or SCSS that you need.
The easiest way to include Compass as an NPM dependency in your next project is through VCU’s NPM registry. Compass is hosted on a private software distribution server, and installing it via this method requires you to be on VCU’s network.
npm install cwf --registry=https://nexus.ts.vcu.edu/repository/vcu-npm/
To avoid having to include the registry flag every time you install Compass, set your global or project’s NPM registry to VCU’s NPM registry. Our recommendation is to use VCU’s NPM registry globally, as it’s the simplest solution with little-to-no project maintenance.
# Global configuration
echo 'registry=https://nexus.ts.vcu.edu/repository/vcu-npm/' > ~/.npmrc
# Project configuration
cd my-project
echo 'registry=https://nexus.ts.vcu.edu/repository/vcu-npm/' > .npmrc
With VCU’s NPM registry set as your default, you can now install Compass like any other package.
npm install cwf
If you don’t want to use VCU’s NPM registry, you can install Compass as an NPM dependency from our SCM repo via Git.
npm install git+ssh://git@scm.vcu.edu:7999/cwf/core.git
We don’t recommend this option, as installing via Git causes maintenance issues, such as no version tracking (so NPM will always say Compass is outdated).
If you’re using a build-system that uses something like Webpack with support for ES2015+ modules, you can import any Compass component JS as follows:
// Nav class (default)
import Nav from 'cwf/components/nav';
// Nav class (explicit)
import { Nav } from 'cwf/components/nav';
If you want to include and run all Compass JS, just import the whole package:
// All Compass JS
import 'cwf';
You can import any Compass SCSS files as follows:
// Nav styles
@import 'path/to/node_modules/cwf/components/nav';
If you are using a version of the SASS compiler that does not support index file resolution, you may need to alter your statements as follows:
// Nav styles (with index file explictly given)
@import 'path/to/node_modules/cwf/components/nav/index';
You can avoid having to type the full path to Compass within the node_modules
directory by resolving its path within your build system. For Gulp (which is what Compass uses for converting SCSS to CSS), you can do the following within your SCSS task:
...
.pipe(gulpSass({
includePaths: [ 'node_modules' ]
}))
...
This allows you to write the following, which is much simpler and easier to remember:
// Nav styles (with node_modules path resolved)
@import 'cwf/components/nav';
If you want to use all Compass SCSS, just import the whole package:
// All Compass styles (with node_modules path resolved)
@import 'cwf';
To install the repo as an easy way to bootstrap your static Compass site development, clone the repo and install all the required dependencies.
git clone ssh://git@scm.vcu.edu:7999/cwf/core.git compass-web-framework
cd compass-web-framework
npm i
This repo was setup using the long-term support release of Node, which at the time of writing is v14.15.4, and NPM v6.14.11. While you may have little to no issues setting up and running the repo with a newer version of Node, this has not been tested. To make this process easier, we recommend using nvm
to manage Node versions, as this repo includes an .nvmrc
to tell nvm
which Node version to use when working within the project.
# To develop assets and live-reload them locally
npm run develop
npm run dev
npm run start
# To build production assets...
npm run build
# ... and then to see them locally
npm run serve
At the time of writing, this project supports the last two major versions of Chrome, Edge, Firefox, Opera and Safari as noted in the project’s package.json
:
defaults and last 2 versions, not Explorer <= 11, not ExplorerMobile 11
A full list of supported browsers can be visualized at browserl.ist.
The grid component utilizes features that will not work in Baidu/Opera Mini browsers.
Information regarding Compass’ lack of Internet Explorer support is documented on the FAQ page of our main site.
As the project progresses and grows, it’s important to ensure consistency in the way the code is written and structured. The following are guidelines on how best to do so.
Compass’ build system has two distinct modes: development and production. Development mode will build out the assets unminified, and is useful for testing purposes. Production mode will build out the assets minified and altered (such as the removal of redundant code or the simplification of variable names), and is used for implementation in production. Commands such as develop
, dev
, or start
are automatically ran in development mode, whereas build
is automatically ran in production mode.
NODE_ENV=development
.NODE_ENV=production
.Javascript is to be written in vanilla, ES2015+ syntax; This is to ensure the JS is future proof, clean, and compartmentalized. This is converted to JS targeted for the browsers found in the browsers list in the package.json
using the Gulp build system.
When writing JS, try and make things reusable by bundling functional logic in a module to later be imported in. In addition, do not use JS frameworks and only use JS dependencies through NPM where absolutely necessary. In addition, please have an ESLint linter running to enforce code style.
JS can be transpiled separately by running npx gulp js
.
SCSS is to be written as opposed to SASS; This is to ensure it’s closer to vanilla CSS which helps with onboarding. This is converted to CSS using the Gulp build system, which does the following:
package.json
The SCSS should be divided up into partials associated with components and follow a BEM structure. This BEM structure is to use double underscores/dashes and no block nesting (or grandchild selectors) when writing classes. Try to keep class nesting to a minimum. Compass-specific component classes (or non content-related classes, such as the header, footer, navigation, etc.) must be prefixed with cwf-
. Media queries are to be written using the bubbling method, as it is considered industry standard when using SASS/SCSS. Finally, do not use SASS/SCSS frameworks. SCSS partials should include variables and mixins explicitly, as it allows users to pick and choose which partials to pull in without having to a). pull in all of Compass, or b). know what variables/mixins to pull in along with it (see the _reset.scss
partial as an example).
SCSS can be transpiled separately by running npx gulp scss
.
Twig is an HTML templating engine, and this repo uses a Twig.js implementation for Gulp. This allows for easy templating integration and seperating of data/structure. Components and layouts should be within different folders. It is encouraged to download syntax highlighting for Twig in your code editor of choice. It should be noted that at the time of writing, the Gulp implementation of Twig.js used (gulp-twig
) hasn’t been regularly maintained; Should you run into any problems templating HTML assets, inform the Compass team of the problem.
HTML can be transpiled separately by running npx run twig
.
JS linting is handled through ESLint. This can be utilized by your code editor of choice, or can be manually ran using the npm run lint
script. The ESLint configuration includes but is not limited to:
import/export
modules instead of CommonJS modulesThere are pre-commit Git hooks that will lint your JS files (see above) and check to see if all source files are formatted correctly (see below) before committing.
Formatting of all source files is handled through Prettier. This can be manually checked using npm run check
and ran using the npm run format
script. The Prettier configuration includes, but is not limited to:
If you are contributing to this project, please be sure to follow the above guidelines. In addition, please add your name to the contributors array found within the package.json
file, the format of which should be First Last <email>
.