A command-line utility to create a repo based on one of Rangle.io's standard tech stacks.
npm install rangle-starter 
A command-line utility to create a repo based on one of Rangle.io's standard tech stacks.
These stacks are designed to play nice with Rangle.io's dev ops tools and
internal workflow. However they are open source and available to the community on an unsupported basis as well.
> Looking for a tech stack that used to be here?
Install it like this:
``
npm install -g rangle-starter
First, create a repository for your new project on github. Leave it empty for
now.
Next, run rangle-starter and answer the questions in order to setup your new project.
This will create a new repo locally based on the appropriate tech stack.
npm install; npm start will build and run the sample app for that stack.
Push up your new repo with:
`sh`
git push upstream master -u
Finally, go back to GitHub and fork your new repo to allow you to work using
Rangle-Flow (see note below).
JavaScript is evolving rapidly, with new approaches to application
development appearing almost on a monthly basis. As a training firm,
one of the services we provide is staying on top of these changes and
advising our clients on contemporary thinking.
On the other hand, as a consultancy, we also need to start up new
projects frequently and quickly, balancing up-to-date technology with
production-level expertise.
These stacks are what we use on our projects to get teams up and running
quickly, with our latest thinking on tools, technologies, and best
practices. However they are also provided, free of warranty, for community
usage under the terms of the MIT license.
Currently, we maintain starters for the following tech stacks:
* Angular 2 with TypeScript
* React with ES6
* Angular 1 with TypeScript and Redux
* API Koa Starter
Regardless of framework, we favour an architectural approach based on
'atomic' components for presentation and Redux for state management. The
code layout and CSS toolchain have been carefully chosen to accomodate
this.
#### Component-Oriented Architecture (COA)
Component-oriented architecture is a way of thinking of apps as render
trees of simple, presentational components. In this line of thinking,
we:
* build out a visual, domain-specific language of reusable UI components
* separate state management and business logic from these UI components as
much as we can.
Good presentational components have the following characteristics:
* They are very granular (even as little as a few lines of HTML)
* They encapsulate any CSS, HTML, and JS need to render themselves
* They are isolated and composable into larger page elements
* They are essentially pure functions that accept some attributes and
produce some DOM.
You can learn more about COA here:
* Atomic Design blog post
* Intro to COA with Angular 2
##### Presentational Components in React
For React, we use 'functional stateless components' to enforce these
concepts. Most of your components will be pure functions of their props
which return snippets of JSX.
Each component gets its own scoped CSS using the
postss-local-by-default transformation.
##### Presentational Components in Angular 2
In Angular 2, we use very granular @Component classes whose rendered@Input
DOM is strictly a function of any properties.
Each component gets its own scoped CSS using Angular 2's ViewEncapsulation
feature.
#### CSS Toolchain
An important aspect of COA is that components are responsible for their
own CSS. To means that we have to overcome the four classic problems
associated with CSS:
1. its global nature
2. its tendency to repeat large sets of rules across different classes
3. its inability to support dynamic features such as variables
4. enormously variable browser support.
We have chosen to address these using a toolchain based on OOCSS utility
classes and 'transpilation'.
##### OOCSS Utility Classes
Utility class libraries in CSS provide a large set of composable,
single-purpose classes that can be reference directly in your component
templates. There are a few good ones, such as tachyons and
basscss; our current favourite is basscss.
Basscss utilities end up taking care of the lion's share of styling for
our components.
##### CSS Transpilation
The other issues listed above are addressed using postcss, a 'transpiler'
for CSS. Postcss allows you to list a set of transformation plugins for your
CSS which can:
* allow @import and variables (cssnext)
* handle vendor prefixing and known workarounds for you (autoprefixer)
* scope CSS to a particular DOM or JSX element (local-by-default
This lets us write component-level CSS files that are properly scoped
and prefixed in the small number of cases where basscss is insufficient.
You can learn more about our CSS strategy from our
Modular CSS training slides.
We take developer experience very seriously. The starters are set up with
the following tools:
* source-map support for debugging the original transpiled code in the
browser
* named functional components for React dev tools (react starters only)
* full support for Augury, the Angluar 2 Dev Tool Extension
* full support for the Redux Devtools Chrome Extension
Running any starter in dev mode will turn on these tools. Simply type
npm run dev and point your browser at http://localhost:8080.
Of course, one of the main motivations of these starters is to have production
bundling set up and easy to go.
Typing npm run build will produce bundled, minified, JS and CSS for
optimal loading speed in most browsers.
Typing npm start will fire up a simple NodeJS server you can use todist
serve your app; alternately you can deploy the contents of the folder
behind the HTTP server of your choice.
We aim to support the same minimum browsers as the frameworks we use.
Currently that means Internet Explorer 9+ and the last two versions of
Chrome and Firefox.
Code quality is important to us. All our starters ship with unit testing
toolchains up and running.
We also use tslint and eslint for static code linting; and finally there
is a selenium-based E2E setup based on the Robot framework.
At Rangle.io we use a fork-and-branch strategy for pull requests, with some
modifications for our internal tooling. Repos set up using this script assume
that your have a central repo for the team and developers work on personal forks.
Therefore the script sets up two remotes:
origin, which points to your personal fork, and upstream, which points to
a team repo which typically belongs your github organization.
If you want to change this, just fiddle with git remote` after running the
script.
For more in-depth discussion of these starters, see our