Skip to content

Commit

Permalink
Merge pull request #237 from edx/talbs/use-npm
Browse files Browse the repository at this point in the history 
Use Node Package Manager (npm)
  • Loading branch information
@talbs
talbs committed Dec 16, 2015
2 parents 815862d + 57a4d84 commit 7ea1310
Show file tree
Hide file tree
Showing 16 changed files with 130 additions and 114 deletions.
21 changes: 21 additions & 0 deletions .npmignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@

.gitignore
404.html
_config.yml
_data
_includes
_layouts
_posts
_site
pldoc
about.md
bower_components
CNAME
examples
favicon.ico
gulp
gulpfile.js
index.html
node_modules
package.json
public
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,11 @@
## unreleased
Nothing yet

- - -

## 0.7.0 (2015-12-14)
* Moving from Bower-based to NPM-based package management

- - -
## 0.6.0 (2015-11-24)
* Revising color patterns to use Sass mix() method
Expand Down
127 changes: 58 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# edX Pattern Library
# edX UX Pattern Library (UXPL)

The (working) UI library and Front End Styleguide for edX/Open edX applications and sites.

Expand All @@ -11,7 +11,7 @@ The (working) UI library and Front End Styleguide for edX/Open edX applications
3. [Dependencies](#dependencies)
4. [Documentation](#documentation)
5. [Development - Documentation Site](#development---documentation-site-pldoc)
6. [Development - UX Pattern Library Package](#development---ux-pattern-library-bower-package)
6. [Development - UX Pattern Library Package](#development---ux-pattern-library-nodejs-package)
7. [Use and Deployment](#use-and-deployment)
8. [Contributions](#contributions)

Expand All @@ -35,7 +35,7 @@ library/blob/master/LICENSE.txt) for details.

Using the edX Pattern Library source code in a project current requires:

* locally installing [Bower](http://bower.io/) - [see below](#development---ux-pattern-library-package) for more installation details.
* locally installing a package manager [a package manager (either [Node/npm](https://nodejs.org) or [Bower)](http://bower.io/).
* Use of modern web browsers - see [Open edX/edX browser support](http://docstrings.readthedocs.org/en/latest/front_matter/browsers.html)
* the use and compilation of Sass into CSS using perferrably [LibSass](http://sass-lang.com/libsass) (if using the Sass method for including the pattern library).

Expand All @@ -46,11 +46,11 @@ Also, the Pattern Library currently relies on the following thrd party libraries

| Library | Version | Purpose |
| ------------- | ------------- | ------------- |
| [Bourbon](https://github.com/thoughtbot/bourbon) | 4.2.3 | basic sass/CSS utilities |
| [Animate.css](https://github.com/daneden/animate.css) | 3.3.0 | pre-set CSS animations |
| [Bourbon](https://github.com/thoughtbot/bourbon) | 4.2.6 | basic sass/CSS utilities |
| [Animate.css](https://github.com/daneden/animate.css) | 3.4.0 | pre-set CSS animations |
| [bi-app-sass](https://github.com/anasnakawa/bi-app-sass) | latest | right-to-left/left-to-right directional support for layouts |
| [breakpoint-sass](https://github.com/at-import/breakpoint) | 2.6.1 | CSS breakpoint/media-query management |
| [susy](https://github.com/ericam/susy) | 2.2.5 | Grid configuration and utilities |
| [susy](https://github.com/ericam/susy) | 2.2.9 | Grid configuration and utilities |
| [A Font Garde](https://github.com/filamentgroup/a-font-garde) | 0.1.6 | A set of reliable (nay, bulletproof) patterns for icon fonts. |

## Documentation
Expand All @@ -68,8 +68,7 @@ recent versions of the following things installed on your local machine.
| Library | Version | Purpose |
| ------------- | ------------- | ------------- |
| [Bundler](http://bundler.io/) | 1.10 | Used to install [jekyll](http://jekyllrb.com) and its dependencies |
| [Node.js](http://nodejs.org/) | 0.12.x or 4.0.x | Support for the asset pipeline |
| [Bower](http://bower.io/) | 1.5.0 | fetch and compile javascript assets |
| [Node.js](http://nodejs.org/) | 0.12.x or 4.0.x | Third-party dependency package management
| [GulpJS](https://github.com/gulpjs/gulp) + other gulp-based packages | 3.9.0 | Task runner for build process |


Expand Down Expand Up @@ -105,42 +104,13 @@ docs](http://jekyllrb.com/docs/templates/#code_snippet_highlighting).

- - -

### Step 2: Install Node.js
### Step 2: Install Node.js and Node Package Manager (npm)

If you've never used Node or npm before, you'll need to install Node. If you use
homebrew, do:

```
brew install node
```

Otherwise, you can download and install from [here](http://nodejs.org/download/).

- - -

### Step 3: Install Bower

After instaling Node.js, you can install [Bower](http://bower.io/), a package
manager we use to download and maintain many of our vendor and external library
refereces.

To install Bower globally:
```
npm install -g bower
```

After Bower is installed, you can install all of the edX UX Pattern Library
dependecies with:

```
bower install
```

**NOTE**: Bower files should not be edited or removed outside of the Bower workflow.
The npm command-line tool is bundled with [Node.js](https://nodejs.org). If you have it installed, then you already have npm too. If not, go [download Node.js](https://nodejs.org/en/download/).

- - -

### Step 4: Install/Update Gulp + Project Dependencies
### Step 3: Install Project Dependencies & Gulp Task Flow

From the directory you've checked out this repo into locally, run:

Expand All @@ -149,7 +119,7 @@ npm install
```

This runs through all dependencies listed in package.json and downloads them to
a node_modules folder in your project directory.
a `node_modules` folder in your project directory.

**NOTE:** You may need to run this more than just once (if encountering errors
when running the gulp command) as new dependencies may have been added.
Expand All @@ -163,7 +133,7 @@ this project, run:

- - -

### Step 5: Run Locally (w/ Gulp Workflow)
### Step 4: Run Locally (w/ Gulp Workflow)

To view the Pattern Library locally (and to watch for any local changes to
content/assets), run the `default` gulp task with:
Expand All @@ -177,23 +147,23 @@ This will run the `default` gulp task defined in `gulpfile.js`, which includes t
After running the default task, your local instance of the Pattern Library can
be viewable at http://localhost:3000. There are additional views:

* http://localhost:3000/examples/**/* - where full page examples and demos are kept
* http://localhost:3000/patterns/**/* - permalinks for individually documented pattern library patterns
* ``http://localhost:3000/examples/**/*`` - where full page examples and demos are kept
* ``http://localhost:3000/patterns/**/*`` - permalinks for individually documented pattern library patterns
- - -

### Committing Code to PLDOC

When developing changes or new work within the PLDOC, please make sure to:

1. leave the Pattern Library Source Code (contained in ``pattern-ibrary``) unedited (or edit in a separate branch/commit)
1. leave the Pattern Library Source Code (contained in ``pattern-library``) unedited (or edit in a separate branch/commit)
2. run the production preparation-focused gulp task ``gulp build-production``, which will optimize any checked in production assets (styles, images, and scripts), if you've added or heavily edited new PLDOC assets.

## Development - UX Pattern Library Bower Package
## Development - UX Pattern Library Package

If you add or edit any patterns in this repo (found in ``_src/pattern-library/``) or change any bower-centric settings (e.g. ``bower.json``), please do the following:
If you add or edit any patterns in this repo (found in ``_src/pattern-library/``) or change any package-centric settings (e.g. ``package.json`` or ``bower.json``), please do the following:

1. test that the change you've made will not negatively affect the bower package other apps and codebases are relying on
2. talk to the UX Team about any bumps (based on [semantic versioning](http://semver.org/)) in the bower package's version number that are needed.
1. test that the change you've made will not negatively affect the node package manager (npm) package other apps and codebases are relying on
2. talk to the UX Team about any bumps (based on [semantic versioning](http://semver.org/)) in the npm package's version number that are needed.

- - -

Expand All @@ -203,20 +173,39 @@ The UX Pattern Library is meant to be a starting UI Framework to support edX
and Open edX applications and sites. To start using the UX Pattern Library in an
edX/Open edX app, please follow these steps:

### Step 0: Install and Configure Bower
### Step 0: Install Node
You'll need to [download Node.js](https://nodejs.org/en/download/) in order to use either of the UXPL packages.

After instaling Node.js, you can install [Bower](http://bower.io/), a package
manager we use to download and maintain many of our vendor and external library
refereces.
### Step 1: Install and Configure UXPL Packages
Next, you'll want to add the edx-pattern-library registered package as a dependency for your project and install it all at once. You have a few options for what package manager to do that through:

#### Using Node
In your project's main directory, you'll need to create a ``package.json`` file that will manage locally installed npm packages. To create a package.json run:

To install Bower globally:
```
npm install -g bower
$ npm init
```

- - -
You'll be walked through some basic settings for your project's package. See also [npm's documentation on setting up a package](https://docs.npmjs.com/getting-started/using-a-package.json).


Next, you'll want to add the ``edx-pattern-library`` registered package as a dependency for your project and install it all at once.

```
$ npm install edx-pattern-library --save
```

### Step 1: Install/List the UX Pattern Library Package as a Dependency
See also, [npm's documentation on installing/saving dependencies](https://docs.npmjs.com/getting-started/using-a-package.json#the-save-and-save-dev-install-flags).


#### Using Bower
After instaling Node.js, you can install [Bower](http://bower.io/), a package manager we use to download and maintain many of our vendor and external library refereces.

To install Bower globally:

```
npm install -g bower
```

Next, you'll want to add the ``edx-pattern-library`` registered package as a
bower dependency and install it all at once.
Expand All @@ -225,7 +214,7 @@ bower dependency and install it all at once.
bower install edx-pattern-library --save
```

**NOTE:** Bower recommends initializing your project as a bower project in order to manage third party dependencies such as the 'edx-pattern-library' bower package. [Bower explains how to do that well with bower.json``](http://bower.io/docs/creating-packages/#bowerjson).
**NOTE:** Bower recommends initializing your project as a bower project in order to manage third party dependencies such as the `edx-pattern-library` bower package. [Bower explains how to do that well with bower.json](http://bower.io/docs/creating-packages/#bowerjson).

- - -

Expand All @@ -235,10 +224,10 @@ bower install edx-pattern-library --save
You can use the edX UX Pattern Library as a static CSS base alongside other CSS files. To do so add a reference in the ``<head>`` of your app's HTML

```html
<link rel="stylesheet" href="[path to your bower or manually managed assets]/edx-pattern-library-ltr.min.css" />
<link rel="stylesheet" href="[path to your package manager (npm or bower) or manually managed assets]/edx-pattern-library-ltr.min.css" />
```

**NOTE**: The Bower package comes with several variations of compiled CSS, including:
**NOTE**: The node package manager (npm) package comes with several variations of compiled CSS, including:

* RTL and LTR support - noted by either a ``*-ltr`` or ``*-rtl`` suffix)
* Minified and expanded CSS output formats - for production and development/debugging purposes respectively.
Expand Down Expand Up @@ -270,7 +259,7 @@ $layout-direction: ltr;
// #LIB
// ------------------------------
@import 'lib';
@import '{path to edx-pattern-library Bower package}/pattern-library/sass/edx-pattern-library';
@import '{path to edx-pattern-library package}/pattern-library/sass/edx-pattern-library';


// ------------------------------
Expand All @@ -284,12 +273,12 @@ $layout-direction: ltr;

```

**NOTE**: Since both libSass and RubySass lack a way to pass in variables/configuration into their ``@import {file}`` method, each app is responsible for 1) storing any bower-based dependencies, including the edx-pattern-library, in the best directory structure for that app's set up and 2) creating a ``_lib.scss`` partial to import all third party library dependencies from that structure for the Pattern Library to use (see above example).
**NOTE**: Since both libSass and RubySass lack a way to pass in variables/configuration into their ``@import {file}`` method, each app is responsible for 1) storing any npm-based dependencies, including the edx-pattern-library, in the best directory structure for that app's set up and 2) creating a ``_lib.scss`` partial to import all third party library dependencies from that structure for the Pattern Library to use (see above example).

See [the UX Pattern Library Files + Application Files guidelines](https://github.com/edx/ux-pattern-library/wiki/Styleguide:-Sass-&-CSS#ux-pattern-library-files--application-files) and [example style compile](https://github.com/edx/ux-pattern-library/wiki/Styleguide:-Sass-&-CSS#main-style-compile) for more examples, details on how to use partials, and general background.

##### Custom Reference/Import
If you'd like to customize what to import, you can manually import specific elements from the bower package. Here's an example of customizing the default import demo above:
If you'd like to customize what to import, you can manually import specific elements from the edx-pattern-library package. Here's an example of customizing the default import demo above:

```scss
// ------------------------------
Expand All @@ -309,14 +298,14 @@ $layout-direction: ltr;
// #LIB
// ------------------------------
@import 'lib';
@import '{path to edx-pattern-library Bower package}/pattern-library/sass/global/core';
@import '{path to edx-pattern-library package}/pattern-library/sass/global/core';

// use UXPL's buttons, headings, copy, grid, and layouts
@import '{path to edx-pattern-library Bower package}/pattern-library/sass/patterns/buttons';
@import '{path to edx-pattern-library Bower package}/pattern-library/sass/patterns/headings';
@import '{path to edx-pattern-library Bower package}/pattern-library/sass/patterns/copy';
@import '{path to edx-pattern-library Bower package}/pattern-library/sass/patterns/grid';
@import '{path to edx-pattern-library Bower package}/pattern-library/sass/patterns/layouts';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/buttons';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/headings';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/copy';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/grid';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/layouts';


// ------------------------------
Expand Down
2 changes: 1 addition & 1 deletion bower.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "edx-pattern-library",
"version": "0.6.0",
"version": "0.7.0",
"authors": [
"edX UX Team <[email protected]>"
],
Expand Down
2 changes: 1 addition & 1 deletion gulp/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ module.exports = {
},
lib: {
// third party libraries
src: './bower_components'
src: './node_modules'
},
jekyll: {
home: 'index.html',
Expand Down
37 changes: 32 additions & 5 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,33 @@
{
"name": "edx-ux-pattern-library",
"version": "0.2.0",
"name": "edx-pattern-library",
"version": "0.7.0",
"author": "edX UX Team <[email protected]>",
"license": "Apache-2.0",
"description": "Gulp and Jekyll front end workflow with common tasks for edX's UX Pattern Library site",
"description": "The (working) Visual, UI, and Front End Styleguide for edX Apps",
"keywords": [
"atomic design",
"edx",
"open edx",
"patterns",
"pattern library",
"UI starter"
],
"homepage": "http://ux.edx.org",
"main": "_settings.scss",
"repository": {
"type": "git",
"url": "git://github.com/edx/ux-pattern-library.git"
},
"dependencies": {
"animate.css": "^3.4.0",
"bi-app-sass": "^1.1.0",
"bourbon": "^4.2.6",
"breakpoint-sass": "^2.6.1",
"jquery": "^1.11.1",
"requirejs": "^2.1.22",
"requirejs-plugins": "^1.0.2",
"susy": "^2.2.9"
},
"devDependencies": {
"browser-sync": "*",
"del": "*",
Expand All @@ -19,7 +40,7 @@
"gulp-imagemin": "*",
"gulp-minify-css": "*",
"gulp-notify": "*",
"gulp-rename": "^1.2.2",
"gulp-rename": "*",
"gulp-sass": "*",
"gulp-sourcemaps": "*",
"gulp-uglify": "*",
Expand All @@ -28,6 +49,12 @@
"lodash": "*",
"merge-stream": "*",
"require-dir": "*",
"run-sequence": "*"
"run-sequence": "*",
"susy": "^2.2.9"
},
"scripts": {
"production": "gulp build-production",
"gulp": "gulp",
"development": "gulp build-development"
}
}
Loading

0 comments on commit 7ea1310

Please sign in to comment.