<commit_before>Our goal with this project is to have a super simple + low barrier to entry for development. All you should need is nodejs + git. There should be be no complexity in the development setup or workflow.

# Setup
```
git clone https://github.com/alm-tools/alm.git
cd alm
npm install
npm link
```

Now you can run `alm`

We highly recommend you use [`nodemon`](https://github.com/remy/nodemon), just run it from the project root:

```
npm install nodemon -g
nodemon
```

# Workflow

Once you have `nodemon` running, if you edit any front-end ts file our Webpack setup will reload the front end only. Make a change to some backend file and the app restarts :rose:

# IDE
We presently use [`atom-typescript`](https://atom.io/packages/atom-typescript). Eventually this project should be self hosting.

```
atom .
```

We critically use it for fast `.ts` -> `.js` workflow.

# Webpack
All our front-end js gets minified into `bundle.js`. This is what gets npm deployed.

For dev time we have a setup (all code in `devtime.ts`) where we start a `WebpackDevServer` and proxy the `bundle.js` requests to it, additionally loading the hot loader to refresh our UI if any front-end JS changes.

The meanings of some key folders:
```
src/app            -> all our front-end (main entry point called `main.ts`)
src/public/build   -> bundle.js and other generated resources go here
src/server         -> our backend code (main entry point called `server.ts`)
src/common         -> Shared between server /client. No server or client only code.
webpack.config.ts  -> our webpack config shared between devtime and what gets npm deployed
```

In addition to that we make it easier to test the app as it would appear after npm publish:

* Visit `/prod` to see the app as it would work after npm publish and then test app. Live reload will be disabled.
* Visit `/dev` to go back to the dev time workflow.

More reading (You don't need to read these ... but if you are bored):
* [Hot reloading docs](https://github.com/webpack/docs/wiki/hot-module-replacement-with-webpack)
* [Some ideas borrowed from here](http://www.christianalfoni.com/articles/2015_04_19_The-ultimate-webpack-setup)

# Server Folder Structure

* `server/workers` we run various background workers. They are present here.
* `server/lang` our main API stuff on top of the core TypeScript Language Service.

# How does the frontend talk to the backend
Documented in the [principles of ASYNC](./ASYNC.md).

# How is global state managed
State for visual components in mostly managed by redux which we have made type-safe. [Checkout the docs](./REDUX.md).

# Conventions
Please see [CONVENTIONS.md](./CONVENTIONS.md)

# Deployment
Please see [DEPLOYMENT.md](./DEPLOYMENT.md)

# Various NPM commands

### After moving a new machine
I quite often work on my personal laptop during my 1 hour one way commute and need to setup the machine quickly, so on the new machine:

```
npm run resume
```

This will just run the right things again (pull + install + initial compile).

### Updating TypeScript Version
We use [NTypeScript](https://github.com/TypeStrong/ntypescript). NTypeScript keeps itself updated with Microsoft/Typescript every night. To update the version used by alm.tools simply run
```
npm run update
```
This will install the latest version of NTypeScript and run a build to make sure everything still compiles.

### Running tsc in watch mode
If you did something which resulted in a lot of errors you can run tsc in watch mode in a new window:

```
npm run tscw
```<commit_msg> idea tracking<commit_after>Our goal with this project is to have a super simple + low barrier to entry for development. All you should need is nodejs + git. There should be be no complexity in the development setup or workflow.

# Setup
```
git clone https://github.com/alm-tools/alm.git
cd alm
npm install
npm link
```

Now you can run `alm`

We highly recommend you use [`nodemon`](https://github.com/remy/nodemon), just run it from the project root:

```
npm install nodemon -g
nodemon
```

# Workflow

Once you have `nodemon` running, if you edit any front-end ts file our Webpack setup will reload the front end only. Make a change to some backend file and the app restarts :rose:

# IDE
We presently use [`atom-typescript`](https://atom.io/packages/atom-typescript). Eventually this project should be self hosting.

```
atom .
```

We critically use it for fast `.ts` -> `.js` workflow.

# Webpack
All our front-end js gets minified into `bundle.js`. This is what gets npm deployed.

For dev time we have a setup (all code in `devtime.ts`) where we start a `WebpackDevServer` and proxy the `bundle.js` requests to it, additionally loading the hot loader to refresh our UI if any front-end JS changes.

The meanings of some key folders:
```
src/app            -> all our front-end (main entry point called `main.ts`)
src/public/build   -> bundle.js and other generated resources go here
src/server         -> our backend code (main entry point called `server.ts`)
src/common         -> Shared between server /client. No server or client only code.
webpack.config.ts  -> our webpack config shared between devtime and what gets npm deployed
```

In addition to that we make it easier to test the app as it would appear after npm publish:

* Visit `/prod` to see the app as it would work after npm publish and then test app. Live reload will be disabled.
* Visit `/dev` to go back to the dev time workflow.

More reading (You don't need to read these ... but if you are bored):
* [Hot reloading docs](https://github.com/webpack/docs/wiki/hot-module-replacement-with-webpack)
* [Some ideas borrowed from here](http://www.christianalfoni.com/articles/2015_04_19_The-ultimate-webpack-setup)

# Server Folder Structure

* `server/workers` we run various background workers. They are present here.
* `server/lang` our main API stuff on top of the core TypeScript Language Service.

# How does the frontend talk to the backend
Documented in the [principles of ASYNC](./ASYNC.md).

# How is global state managed
State for visual components in mostly managed by redux which we have made type-safe. [Checkout the docs](./REDUX.md).

# Conventions
Please see [CONVENTIONS.md](./CONVENTIONS.md)

# Deployment
Please see [DEPLOYMENT.md](./DEPLOYMENT.md)

# Various NPM commands

### After moving a new machine
I quite often work on my personal laptop during my 1 hour one way commute and need to setup the machine quickly, so on the new machine:

```
npm run resume
```

This will just run the right things again (pull + install + initial compile).

### Updating TypeScript Version
We use [NTypeScript](https://github.com/TypeStrong/ntypescript). NTypeScript keeps itself updated with Microsoft/Typescript every night. To update the version used by alm.tools simply run
```
npm run update
```
This will install the latest version of NTypeScript and run a build to make sure everything still compiles.

### Running tsc in watch mode
If you did something which resulted in a lot of errors you can run tsc in watch mode in a new window:

```
npm run tscw
```

# Idea Tracking
Since I am still doing a lot of *thinking* then *rethinking* I'm trying not to put too much stuff in the [issues][issues] as it spams the watchers. Instead I've been using a private trello but its very *raw* (like a pen an paper). Feel free to ask me questions on [gitter][gitter] about what's in my headspace. I try to be open about it on [twitter][twitter] anyways.

[issues]: https://github.com/alm-tools/alm/issues
[gitter]: https://gitter.im/alm-tools/alm
[twitter]: https://twitter.com/basarat
{'fraction_non_alphanumeric': 0.08583070452155625, 'fraction_numerical': 0.002365930599369085, 'mean_word_length': 3.931302657161374, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 13, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '330301', 'n_tokens_mistral': 2234, 'n_tokens_neox': 2100, 'n_words': 1072}