{"id":21575464,"url":"https://github.com/rangle/rangle-starter","last_synced_at":"2025-04-10T16:32:10.818Z","repository":{"id":54365962,"uuid":"49800398","full_name":"rangle/rangle-starter","owner":"rangle","description":null,"archived":false,"fork":false,"pushed_at":"2021-02-23T05:40:36.000Z","size":41,"stargazers_count":48,"open_issues_count":35,"forks_count":23,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-03-24T14:12:56.665Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rangle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-17T02:51:07.000Z","updated_at":"2022-09-06T09:13:57.000Z","dependencies_parsed_at":"2022-08-13T13:31:05.195Z","dependency_job_id":null,"html_url":"https://github.com/rangle/rangle-starter","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rangle%2Frangle-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rangle%2Frangle-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rangle%2Frangle-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rangle%2Frangle-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rangle","download_url":"https://codeload.github.com/rangle/rangle-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247785943,"owners_count":20995644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T12:13:22.150Z","updated_at":"2025-04-10T16:32:10.781Z","avatar_url":"https://github.com/rangle.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rangle-starter\n\n[![Stories in Ready](https://badge.waffle.io/rangle/rangle-starter.png?label=ready\u0026title=Ready)](https://waffle.io/rangle/rangle-starter) [![Join the chat at https://gitter.im/rangle/rangle-starter](https://badges.gitter.im/rangle/rangle-starter.svg)](https://gitter.im/rangle/rangle-starter?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nA command-line utility to create a repo based on one of Rangle.io's standard tech stacks.\n\nThese stacks are designed to play nice with Rangle.io's dev ops tools and\ninternal workflow. However they are open source and available to the community on an unsupported basis as well.\n\n\u003e [Looking for a tech stack that used to be here?](examples.md)\n\n## Installation\n\nInstall it like this:\n\n```\nnpm install -g rangle-starter\n```\n\n## Usage\n\nFirst, create a repository for your new project on github. Leave it empty for\nnow.\n\nNext, run `rangle-starter` and answer the questions in order to setup your new project.\n\nThis will create a new repo locally based on the appropriate tech stack.\n`npm install; npm start` will build and run the sample app for that stack.\n\nPush up your new repo with:\n\n```sh\ngit push upstream master -u\n```\n\nFinally, go back to GitHub and fork your new repo to allow you to work using\nRangle-Flow (see note below).\n\n## About the Stacks\n\nJavaScript is evolving rapidly, with new approaches to application\ndevelopment appearing almost on a monthly basis. As a training firm,\none of the services we provide is staying on top of these changes and\nadvising our clients on contemporary thinking.\n\nOn the other hand, as a consultancy, we also need to start up new\nprojects frequently and quickly, balancing up-to-date technology with\nproduction-level expertise.\n\nThese stacks are what we use on our projects to get teams up and running\nquickly, with our latest thinking on tools, technologies, and best\npractices. However they are also provided, free of warranty, for community\nusage under the terms of the MIT license.\n\nCurrently, we maintain starters for the following tech stacks:\n\n* [Angular 2 with TypeScript](https://github.com/rangle/angular2-starter)\n* [Angular 1 with TypeScript and Redux](https://github.com/rangle/angular-redux-starter)\n* [API Koa Starter](https://github.com/rangle/api-koa-starter)\n\n### React Starter\n\nWe transitioned to Facebook's Create-React-App project for building our react app starters.\n\n* [Facebook's create-react-app](https://github.com/facebookincubator/create-react-app)\n* [Rangle's react-scripts](https://www.npmjs.com/package/@rangle/react-scripts)\n\nTo build a react starter project use the following commands:\n\n```\n// Install\n$ npm install create-react-app -g\n\n// Use our @rangle/scripts with create-react-app to generate react/redux app\n$ create-react-app my-starter-app --scripts-version @rangle/react-scripts\n```\n\n### Code Architecture\n\nRegardless of framework, we favour an architectural approach based on\n'atomic' components for presentation and Redux for state management. The\ncode layout and CSS toolchain have been carefully chosen to accomodate\nthis.\n\n#### Component-Oriented Architecture (COA)\n\nComponent-oriented architecture is a way of thinking of apps as render\ntrees of simple, presentational components.  In this line of thinking,\nwe:\n\n* build out a visual, domain-specific language of reusable UI components\n* separate state management and business logic from these UI components as\nmuch as we can.\n\nGood presentational components have the following characteristics:\n* They are very granular (even as little as a few lines of HTML)\n* They encapsulate any CSS, HTML, and JS need to render themselves\n* They are isolated and composable into larger page elements\n* They are essentially pure functions that accept some attributes and\nproduce some DOM.\n\nYou can learn more about COA here:\n\n* [Atomic Design blog post](http://bradfrost.com/blog/post/atomic-web-design/)\n* [Intro to COA with Angular 2](https://www.youtube.com/watch?v=7cBaE_QwFWQ)\n\n##### Presentational Components in React\n\nFor React, we use 'functional stateless components' to enforce these\nconcepts. Most of your components will be pure functions of their props\nwhich return snippets of JSX.\n\nEach component gets its own scoped CSS using the\n`postss-local-by-default` transformation.\n\n##### Presentational Components in Angular 2\n\nIn Angular 2, we use very granular `@Component` classes whose rendered\nDOM is strictly a function of any `@Input` properties.\n\nEach component gets its own scoped CSS using Angular 2's `ViewEncapsulation`\nfeature.\n\n#### CSS Toolchain\n\nAn important aspect of COA is that components are responsible for their\nown CSS. To means that we have to overcome the four classic problems\nassociated with CSS:\n\n1. its global nature\n2. its tendency to repeat large sets of rules across different classes\n3. its inability to support dynamic features such as variables\n4. enormously variable browser support.\n\nWe have chosen to address these using a toolchain based on OOCSS utility\nclasses and 'transpilation'.\n\n##### OOCSS Utility Classes\n\nUtility class libraries in CSS provide a large set of composable,\nsingle-purpose classes that can be reference directly in your component\ntemplates.  There are a few good ones, such as [tachyons](http://tachyons.io/) and\n[basscss](http://www.basscss.com); our current favourite is basscss.\n\nBasscss utilities end up taking care of the lion's share of styling for\nour components.\n\n##### CSS Transpilation\n\nThe other issues listed above are addressed using `postcss`, a 'transpiler'\nfor CSS. Postcss allows you to list a set of transformation plugins for your\nCSS which can:\n\n* allow `@import` and `variables` ([cssnext](http://cssnext.io/))\n* handle vendor prefixing and known workarounds for you ([autoprefixer](https://autoprefixer.github.io/))\n* scope CSS to a particular DOM or JSX element ([local-by-default](https://github.com/css-modules/postcss-modules-local-by-default)\n\nThis lets us write component-level CSS files that are properly scoped\nand prefixed in the small number of cases where basscss is insufficient.\n\nYou can learn more about our CSS strategy from our\n[Modular CSS training slides](http://rangle.github.io/intro-to-modular-css/).\n\n### Developer Experience\n\nWe take developer experience very seriously. The starters are set up with\nthe following tools:\n\n* source-map support for debugging the original transpiled code in the\nbrowser\n* named functional components for React dev tools (react starters only)\n* full support for Augury, the [Angluar 2 Dev Tool Extension](https://augury.angular.io/)\n* full support for the [Redux Devtools Chrome Extension](https://github.com/zalmoxisus/redux-devtools-extension)\n\nRunning any starter in dev mode will turn on these tools. Simply type\n`npm run dev` and point your browser at http://localhost:8080.\n\n### Building for Production\n\nOf course, one of the main motivations of these starters is to have production\nbundling set up and easy to go.\n\nTyping `npm run build` will produce bundled, minified, JS and CSS for\noptimal loading speed in most browsers.\n\nTyping `npm start` will fire up a simple NodeJS server you can use to\nserve your app; alternately you can deploy the contents of the `dist` folder\nbehind the HTTP server of your choice.\n\n### Browser Support\n\nWe aim to support the same minimum browsers as the frameworks we use.\nCurrently that means Internet Explorer 9+ and the last two versions of\nChrome and Firefox.\n\n### Quality Tools\n\nCode quality is important to us. All our starters ship with unit testing\ntoolchains up and running.\n\nWe also use tslint and eslint for static code linting; and finally there\nis a selenium-based E2E setup based on the Robot framework.\n\n## A note on Rangle-flow\n\nAt Rangle.io we use a fork-and-branch strategy for pull requests, with some\nmodifications for our internal tooling.  Repos set up using this script assume\nthat your have a central repo for the team and developers work on personal forks.\n\nTherefore the script sets up two remotes:\n\n`origin`, which points to your personal fork, and `upstream`, which points to\na team repo which typically belongs your github organization.\n\nIf you want to change this, just fiddle with `git remote` after running the\nscript.\n\n## More Info\n\nFor more in-depth discussion of these starters, see our\n\n* [Blog Post](http://blog.rangle.io/real-world-javascript-standard-tech-stacks/)\n* [React DevMonth Talk](https://www.youtube.com/watch?v=Sy4zy0NPcpo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frangle%2Frangle-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frangle%2Frangle-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frangle%2Frangle-starter/lists"}