chore: Yarn Workspaces (#314)

okta · Sep 27, 2018 · c8b7ab5 · c8b7ab5
1 parent bf6bcfb
commit c8b7ab5
Show file tree

Hide file tree

Showing 53 changed files with 32,894 additions and 89,071 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,9 @@ npm-debug.log
 .envrc
 *.code-workspace
 lerna-debug.log
+yarn-debug.log*
+yarn-error.log*
+package-lock.json
 
 # Ignore TCK-related files in all folders
 okta-oidc-tck*

diff --git a/.travis.yml b/.travis.yml
@@ -10,16 +10,16 @@ addons:
       - oracle-java8-set-default
 
 script:
-- npm install
-- npm run bootstrap
+- yarn install
 - sh ./scripts/runTests.sh
 - bash ./scripts/snyk.sh
 
 install:
-- npm install
+- yarn install
 
 before_install:
-- "npm install -g npm@5.6.0"
+- curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.9.4
+- export PATH="$HOME/.yarn/bin:$PATH"
 - export DISPLAY=:99.0
 - sh -e /etc/init.d/xvfb start
 - sudo apt-get update

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,9 +8,9 @@ Thank you for your interest in contributing to Okta's Open Source Projects! Befo
 
 We use a simplified form of [Atom's](https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages) commit convention.
 
-  * Use the present tense ("Adds feature" not "Added feature")
-  * Limit the first line to 72 characters or less
-  * Add one feature per commit. If you have multiple features, have multiple commits.
+* Use the present tense ("Adds feature" not "Added feature")
+* Limit the first line to 72 characters or less
+* Add one feature per commit. If you have multiple features, have multiple commits.
 
 #### Template
 
@@ -21,69 +21,26 @@ We use a simplified form of [Atom's](https://github.com/atom/atom/blob/master/CO
     Resolves: <Jira # or Issue #>
 
 #### Emoji Categories
+
 Our categories include:
-  * :seedling: `:seedling:` when creating a new feature
-  * :bug: `:bug:` when fixing a bug
-  * :white_check_mark: `:white_check_mark:` when adding tests
-  * :art: `:art:` when improving the format/structure of the code
-  * :memo: `:memo:` when writing docs
-  * :fire: `:fire:` when removing code or files
-  * :package: `:package:` when pushing a new release
-  * :arrow_up: `:arrow_up:` when upgrading dependencies, or generating files
-  * :arrow_down: `:arrow_down:` when downgrading dependencies
+
+* :seedling: `:seedling:` when creating a new feature
+* :bug: `:bug:` when fixing a bug
+* :white_check_mark: `:white_check_mark:` when adding tests
+* :art: `:art:` when improving the format/structure of the code
+* :memo: `:memo:` when writing docs
+* :fire: `:fire:` when removing code or files
+* :package: `:package:` when pushing a new release
+* :arrow_up: `:arrow_up:` when upgrading dependencies, or generating files
+* :arrow_down: `:arrow_down:` when downgrading dependencies
 
 If you do not see an exact emoji match, use the best matching emoji.
 
 #### Example
+
     :memo: Updates CONTRIBUTING.md
 
     Updates Contributing.md with new emoji categories
     Updates Contributing.md with new template
 
     Resolves: #1234
-
-
-## Running Tests locally
-
-You can run tests is each individual package by navigating to the package and running `npm test`.
-E.g:
-
-```bash
-# At project root
-cd packages/oidc-middleware
-npm install
-npm test
-```
-
-You can also run all the tests inside each of the packages from the project root.
-
-For that, you will need to install the dependencies of each package. This can be performed via the following commands:
-
-```bash
-# At project root
-npm install
-npm run bootstrap
-```
-
-> **Note:** Since the packages contain libraries for both Single-Page applications and Web Applications, you will need to create an SPA and Web App in your okta org.
->
-> For the SPA, set the following login redirect URIs - `http://localhost:8080/implicit/callback` & `http://localhost:3000/implicit/callback`
->
-> For the Web App, set the following login redirect URI - `http://localhost:8080/authorization-code/callback`
-
-Next, setup the following environment variables:
-
-```bash
-export ISSUER=https://{your-okta-org-url}/oauth2/default
-export SPA_CLIENT_ID={yourSPAClientId}
-export WEB_CLIENT_ID={yourWebAppClientId}
-export CLIENT_SECRET={yourWebAppClientSecret}
-export USERNAME={yourOktaOrgLoginName}
-export PASSWORD={yourOktaOrgLoginPassword}
-```
-
-After setting up the environment variables, run the following command to run all tests in the packages
-
-```bash
-npm test
-```
diff --git a/README.md b/README.md
@@ -3,13 +3,141 @@ This is a monorepo that contains Okta's OpenID Connect JavaScript resources.
 
 [![build status](https://img.shields.io/travis/okta/okta-oidc-js/master.svg?style=flat-square)](https://travis-ci.org/okta/okta-oidc-js)
 
-## Available packages
-
-|Package    | Status   |  Description |
-|-----------|----------|--------------|
-| [**jwt-verifier**](/packages/jwt-verifier) | [![npm version](https://img.shields.io/npm/v/@okta/jwt-verifier.svg?style=flat-square)](https://www.npmjs.com/package/@okta/jwt-verifier) | Easily verify JWTs from Okta   |
-| [**okta-angular**](/packages/okta-angular) | [![npm version](https://img.shields.io/npm/v/@okta/okta-angular.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-angular) | Angular support for Okta
-| [**oidc-middleware**](/packages/oidc-middleware) | [![npm version](https://img.shields.io/npm/v/@okta/oidc-middleware.svg?style=flat-square)](https://www.npmjs.com/package/@okta/oidc-middleware) | Middleware to easily add OpenID Connect to the Node.js framework of your choice
-| [**okta-react**](/packages/okta-react) | [![npm version](https://img.shields.io/npm/v/@okta/okta-react.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-react) | React support for Okta
-| [**okta-react-native**](/packages/okta-react-native) | [![npm version](https://img.shields.io/npm/v/@okta/okta-react-native.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-react-native) | React Native support for Okta
-| [**okta-vue**](/packages/okta-vue) | [![npm version](https://img.shields.io/npm/v/@okta/okta-vue.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-vue) | Vue.js support for Okta
+**Table of Contents**
+
+- [Getting Started](#getting-started)
+- [Packages](#packages)
+  - [Monorepo](#monorepo)
+  - [Versioning](#versioning)
+  - [Public packages](#public-packages)
+- [Configuration Reference](#configuration-reference)
+- [Testing](#testing)
+  - [Prerequisites](#prerequisites)
+    - [Create a SPA](#create-a-spa)
+    - [Create a Web App](#create-a-web-app)
+  - [Test an individual package](#test-an-individual-package)
+  - [Test all packages](#test-all-packages)
+- [Contributing](#contributing)
+
+## Getting Started
+
+We use Yarn as our node package manager. To install Yarn, check out their [install documentation](https://yarnpkg.com/en/docs/install).
+
+```bash
+# Clone the repo and navigate to it
+git clone git@github.com:okta/okta-oidc-js.git
+cd okta-oidc-js
+
+# Install dependencies
+yarn install
+```
+
+## Packages
+
+### Monorepo
+
+The okta-oidc-js repo is managed as a **monorepo** using [Yarn Workspaces](https://yarnpkg.com/blog/2017/08/02/introducing-workspaces/) for managing dependencies and [Lerna](https://lernajs.io/) for everything else. You can think of each package as a separate npm module - each must list out its own dependencies, have its own package name, and be versioned.
+
+Packages are parsed from the `workspaces` property in [package.json](package.json), and adhere to this structure:
+
+```bash
+packages/
+  jwt-verifier
+  oidc-middleware
+  okta-angular
+  okta-react
+  okta-react-native
+  okta-vue
+```
+
+### Versioning
+
+We've configured Lerna with [independent mode](https://github.com/lerna/lerna/#independent-mode---independent), which means that each package is required to manage its own version number.
+
+### Public packages
+
+| Package                                              | Status                                                                                                                                              | Description                                                                     |
+|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| [**jwt-verifier**](/packages/jwt-verifier)           | [![npm version](https://img.shields.io/npm/v/@okta/jwt-verifier.svg?style=flat-square)](https://www.npmjs.com/package/@okta/jwt-verifier)           | Easily verify JWTs from Okta                                                    |
+| [**okta-angular**](/packages/okta-angular)           | [![npm version](https://img.shields.io/npm/v/@okta/okta-angular.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-angular)           | Angular support for Okta                                                        |
+| [**oidc-middleware**](/packages/oidc-middleware)     | [![npm version](https://img.shields.io/npm/v/@okta/oidc-middleware.svg?style=flat-square)](https://www.npmjs.com/package/@okta/oidc-middleware)     | Middleware to easily add OpenID Connect to the Node.js framework of your choice |
+| [**okta-react**](/packages/okta-react)               | [![npm version](https://img.shields.io/npm/v/@okta/okta-react.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-react)               | React support for Okta                                                          |
+| [**okta-react-native**](/packages/okta-react-native) | [![npm version](https://img.shields.io/npm/v/@okta/okta-react-native.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-react-native) | React Native support for Okta                                                   |
+| [**okta-vue**](/packages/okta-vue)                   | [![npm version](https://img.shields.io/npm/v/@okta/okta-vue.svg?style=flat-square)](https://www.npmjs.com/package/@okta/okta-vue)                   | Vue.js support for Okta                                                         |
+
+## Configuration Reference
+
+Each package is configured to look for environment variables based on the application type.
+
+```bash
+# Navigate into a specific package
+cd packages/${packageName}
+
+# Set the following environment variables
+#
+# ISSUER        - your authorization server
+# CLIENT_ID     - the client ID of your app
+# CLIENT_SECRET - the client secret of your app, required for the oidc-middleware package
+# USERNAME      - username of app user, required for tests
+# PASSWORD      - password of app user, required for tests
+export ISSUER=https://{yourOktaDomain}/oauth2/default
+...
+```
+
+## Testing
+
+Since the workspace contains libraries for Single-Page and Web Applications, you will need to have created a SPA and Web App in your Okta org.
+
+### Prerequisites
+
+#### Create a SPA
+
+1. Applications > Add Application
+2. Select SPA
+3. Add the following **login redirect URI**:
+    - `http://localhost:8080/implicit/callback`
+    - `http://localhost:3000/implicit/callback`
+4. Click Done
+5. Users > Add Person
+6. Create and activate user
+
+#### Create a Web App
+
+1. Applications > Add Application
+2. Select Web
+3. Add the following **login redirect URI**:
+    - `http://localhost:8080/authorization-code/callback`
+4. Click Done
+5. Users > Add Person
+6. Create and activate user
+
+### Test an individual package
+
+```bash
+# Navigate into a specific package
+cd packages/${packageName}
+
+# Run the test suite
+yarn test
+```
+
+### Test all packages
+
+Define the following environment variables at the project root and run the tests:
+
+```bash
+# Perform exports at the root of the repository
+[okta-oidc-js]$ export ISSUER=https://{yourOktaDomain}/oauth2/default
+[okta-oidc-js]$ export SPA_CLIENT_ID={SPAClientID}
+[okta-oidc-js]$ export WEB_CLIENT_ID={webAppClientID}
+[okta-oidc-js]$ export CLIENT_SECRET={webAppClientSecret}
+[okta-oidc-js]$ export USERNAME={username}
+[okta-oidc-js]$ export PASSWORD={password}
+
+# Run all tests
+[okta-oidc-js]$ yarn test
+```
+
+## Contributing
+
+We're happy to accept contributions and PRs! Please see the [contribution guide](/CONTRIBUTING.md) to understand how to structure a contribution.
diff --git a/lerna.json b/lerna.json
@@ -1,8 +1,6 @@
 {
   "lerna": "2.1.0",
-  "packages": [
-    "packages/*"
-  ],
   "version": "independent",
-  "hoist": false
+  "npmClient": "yarn",
+  "useWorkspaces": true
 }