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 🌹
NOTE: if you plan to work on a new feature please ask on gitter first https://gitter.im/alm-tools/alm. We are focused on a great default UX with limited customizability so not all features will be accepted.
- git (If you are windows please install the version of git that has git bash and run
npm installfrom that).
- node v5+
git clone https://github.com/alm-tools/alm.git cd alm npm install
Also you can use this build version of
alm on another folder e.g.
your project (i.e not our folder with our test files) simply by running:
Once you have
npm start 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 our running nodemon will make the whole app restart 🌹
We use alm to develop alm.
- ONCE (or whenever you want an update): Run
npm run ualmto copy the current alm copy to node_modules
You run two instances of alm, once where you dev, and one where you test what you have written.
Where you dev
npm run almto launch alm to develop alm.
You are free to use some other IDE if you want. You can run
npm run tscwto run the TypeScript in the background in watch mode and use your favorite IDE in the foreground.
Where you test
npm startin another window to start alm in live reload mode. Open the url mentioned in the console.
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:
/prodto see the app as it would work after npm publish and then test app. Live reload will be disabled.
/devto go back to the dev time workflow.
More reading (You don't need to read these ... but if you are bored):
Server Folder Structure
server/workerswe run various background workers. They are present here.
server/langour 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.
How is global state managed
State for visual components in mostly managed by redux which we have made type-safe. Checkout the docs.
Please see conventions.md
Please see 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 byots as it makes more of the compiler API public for our usage.
byots is updated with Microsoft/Typescript every night. To update the version used by alm.tools simply run
npm run uts
This will install the latest version of TypeScript + Byots and run a build to make sure everything still compiles.
tsvariable available globally in our backend / frontend code bases. So you don't need to do any explicit
import * as tsin new files.
Also be sure to checkout the deployment guide.
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
Working on another branch
Get the latest git commits from that branch. Next all you need to do is
npm install. Now run
nodemon like you would normally do.
Since I am still doing a lot of thinking then rethinking I'm trying not to put too much stuff in the 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 about what's in my headspace. I try to be open about it on twitter anyways.