ldx-widgets/README.md

widgets

# LDX web utilities
This repo is for reusable components and utlity methods, which need to be shared across projects. Note: this is not an open source project, and is intended for use in applicaitons internally at a specific company. If you do not work at said company, this code is probably of little use to you.

## Initial setup
This document will serve as a basic guide to getting started with the **ldx-web-utilities** project

#### 1. Install Node Version Manager (nvm) if you don't already have Node installed
Run the nvm install script using the following command in your terminal: `curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.1/install.sh | bash`

#### 2. Install Node versions
Once the nvm install script is completed, you can now install various versions of Node. Start by installing Node v6.9 by running `nvm install 6.9`. 

Nvm will allow you to hot-switch between Node versions when required, using the `nvm use` command. If you have previously installed Node by other means (such as Homebrew), you may need to uninstall that implementation before installing it with nvm.

#### 3. Install repo dependencies
Install the repo's dependencies using `npm install`. Note: you may need to install additional dependencies globally using the `-g` flag, e.g.: `npm install gulp -g`

#### 4. Start development environment
Use the `npm start` command to get the development environment running. This will compile changes to js in the `/dist` folder, as well as run tests after each change. Note that when the code is used as a dependency, only the js is required, so if coffee-script changes are not compiled, they will not be usable in production. ***SO DO NOT SKIP THIS STEP!***

Note: changes are not compiled on startup, so if you forget this step, make a change, then start the dev environment, you must make anohter change to a compilation to take place.

#### 5. Tests, tests, tests
Please ensure that any additions or changes are covered in tests. PRs will not be merged with broken tests or new functionality that is untested.

## Documentation
The widgets in this repository have generated [API docs](./docs) used for props documentation. 

### Re-generating docs
If you have made changes to a component's documentation, and wish to re-generate the doc files, run the following command: `npm run docs`.

## Auto-copying compiled Javascript to your project's node_modules
The default behavior when running `npm start` includes auto-copying of compiled source files to a specified application. 
After changes are made to the source `.coffee` files, the `dist` folder is automatically copied to replace the same folder inside your local project's `node_modules` directory.

The purpose of this is to make it easier to develop this library while providing means for an implementation and/or staging environment for the widgets.

### paths.json
In order for this feature to work properly, you must create a **paths.json** file in the root of this repo. This file is local to your installation, and is ignored by `.gitignore`. This file should contain an array of absolute folder paths to places you want to copy the compiled output:
```json
[
  {
    "PATH": "/Users/andyparisi/Documents/myProjectRoot"
  }
]
```
**Note: If this directory is incorrect or not writeable, you will receive an error when trying to run `npm start`.**

### Running the compiler without auto-copying
If you have issues with the auto-copying feature or do not want to automatically replace your project files as you work, you can disable this feature. Instead, start the process using the Gulp task directly:
```
gulp test --alone
```