From ef0a08faf6bfba9beceb094b8dc779df35c7ab73 Mon Sep 17 00:00:00 2001 From: nixa <4dmitr@gmail.com> Date: Thu, 19 May 2016 17:22:37 +0300 Subject: [PATCH] readme draft --- README.md | 356 ++++++------------------------------------------------ 1 file changed, 35 insertions(+), 321 deletions(-) diff --git a/README.md b/README.md index ee3e54de..5ffa8da7 100644 --- a/README.md +++ b/README.md @@ -1,332 +1,46 @@ -# Blur Admin HTML template based on Angular 2 + Webpack +# Admin HTML template based on Angular 2, Bootstrap 4 and Webpack Admin template made with ♥ by [Akveo team](http://akveo.com/). Follow us on [Twitter](https://twitter.com/akveo_inc) to get latest news about this template first! -# Angular 1.x version -If you are looking for Angular 1.x version, we have it as well! TODO: link to it +## Demo -# Based on -TODO: angular 2, angular 2 starter kit, webpack, etc +TODO: demo link -## Getting Started +## Angular 1.x version +Here you can find Angular 1.x based version: [Blur Admin](http://akveo.github.io/blur-admin/). -### Installation -### Development -### Production +## Based on +Angular 2, Bootstrap 4, Webpack and lots of awesome modules and plugins. -License -------------- -MIT license. +## Documentation +Installation, customization and other useful articles: https://akveo.github.io/ng2-admin/ + +## How can I support developers? +- Star our GitHub repo +- Create pull requests, submit bugs, suggest new features or documentation updates +- Follow us on [Twitter](https://twitter.com/akveo_inc) +- Like our page on [Facebook](https://www.facebook.com/akveo/) + +## Can I hire you guys? +Yes! We are available for hire. Visit [our homepage](http://akveo.com/) or simply leave us a note to [contact@akveo.com](mailto:contact@akveo.com). We will be happy to work with you! + +## Features +* TypeScript +* Webpack +* Responsive layout +* High resolution +* Bootstrap 4 CSS Framework +* Sass +* Angular 2 +* jQuery +* Charts (Chartist, Chart.js) +* Maps (Google, Leaflet, amMap) +* and many more! + +##License +[MIT](LICENSE.txt) license. ### From akveo Enjoy! - -Made with ♥ by [Akveo team](http://akveo.com/). - -### Quick start -**Make sure you have Node version >= 4.0 and NPM >= 3** -> Clone/Download the repo then edit `app.ts` inside [`/src/app/app.ts`](/src/app/app.ts) - -```bash -# clone our repo -# --depth 1 removes all but one .git commit history -git clone --depth 1 https://github.com/angularclass/angular2-webpack-starter.git - -# change directory to our repo -cd angular2-webpack-starter - -# add required global libraries -npm install typings webpack-dev-server rimraf webpack -g - -# install the repo with npm -npm install - -# start the server -npm start - -# use Hot Module Replacement -npm run server:dev:hmr - -# if you're in China use cnpm -# https://github.com/cnpm/cnpm -``` -go to [http://0.0.0.0:3000](http://0.0.0.0:3000) or [http://localhost:3000](http://localhost:3000) in your browser - -# Table of Contents -* [File Structure](#file-structure) -* [Getting Started](#getting-started) - * [Dependencies](#dependencies) - * [Installing](#installing) - * [Running the app](#running-the-app) -* [Configuration](#configuration) -* [Contributing](#contributing) -* [TypeScript](#typescript) -* [Typings](#typings) -* [Frequently asked questions](#frequently-asked-questions) -* [Support, Questions, or Feedback](#support-questions-or-feedback) -* [License](#license) - - -## File Structure -We use the component approach in our starter. This is the new standard for developing Angular apps and a great way to ensure maintainable code by encapsulation of our behavior logic. A component is basically a self contained app usually in a single file or a folder with each concern as a file: style, template, specs, e2e, and component class. Here's how it looks: -``` -angular2-webpack-starter/ - ├──config/ * our configuration - | ├──helpers.js * helper functions for our configuration files - | ├──spec-bundle.js * ignore this magic that sets up our angular 2 testing environment - | ├──karma.conf.js * karma config for our unit tests - | ├──protractor.conf.js * protractor config for our end-to-end tests - │ ├──webpack.dev.js * our development webpack config - │ ├──webpack.prod.js * our production webpack config - │ └──webpack.test.js * our testing webpack config - │ - ├──src/ * our source files that will be compiled to javascript - | ├──main.browser.ts * our entry file for our browser environment - │ │ - | ├──index.html * Index.html: where we generate our index page - │ │ - | ├──polyfills.ts * our polyfills file - │ │ - | ├──vendor.ts * our vendor file - │ │ - │ ├──app/ * WebApp: folder - │ │ ├──app.spec.ts * a simple test of components in app.ts - │ │ ├──app.e2e.ts * a simple end-to-end test for / - │ │ └──app.ts * App.ts: a simple version of our App component components - │ │ - │ └──assets/ * static assets are served here - │ ├──icon/ * our list of icons from www.favicon-generator.org - │ ├──service-worker.js * ignore this. Web App service worker that's not complete yet - │ ├──robots.txt * for search engines to crawl your website - │ └──human.txt * for humans to know who the developers are - │ - │ - ├──tslint.json * typescript lint config - ├──typedoc.json * typescript documentation generator - ├──tsconfig.json * config that webpack uses for typescript - ├──typings.json * our typings manager - └──package.json * what npm uses to manage it's dependencies -``` - -# Getting Started -## Dependencies -What you need to run this app: -* `node` and `npm` (`brew install node`) -* Ensure you're running the latest versions Node `v4.x.x`+ (or `v5.x.x`) and NPM `3.x.x`+ - -Once you have those, you should install these globals with `npm install --global`: -* `webpack` (`npm install --global webpack`) -* `webpack-dev-server` (`npm install --global webpack-dev-server`) -* `karma` (`npm install --global karma-cli`) -* `protractor` (`npm install --global protractor`) -* `typings` (`npm install --global typings`) -* `typescript` (`npm install --global typescript`) - -## Installing -* `fork` this repo -* `clone` your fork -* `npm install` to install all dependencies -* `typings install` to install necessary typings -* `npm run server` to start the dev server in another tab - -## Running the app -After you have installed all dependencies you can now run the app. Run `npm run server` to start a local server using `webpack-dev-server` which will watch, build (in-memory), and reload for you. The port will be displayed to you as `http://0.0.0.0:3000` (or if you prefer IPv6, if you're using `express` server, then it's `http://[::1]:3000/`). - -### server -```bash -# development -npm run server -# production -npm run build:prod -npm run server:prod -``` - -## Other commands - -### build files -```bash -# development -npm run build:dev -# production -npm run build:prod -``` - -### hot module replacement -```bash -npm run server:dev:hmr -``` - -### watch and build files -```bash -npm run watch -``` - -### run tests -```bash -npm run test -``` - -### watch and run our tests -```bash -npm run watch:test -``` - -### run end-to-end tests -```bash -# make sure you have your server running in another terminal -npm run e2e -``` - -### run webdriver (for end-to-end) -```bash -npm run webdriver:update -npm run webdriver:start -``` - -### run Protractor's elementExplorer (for end-to-end) -```bash -npm run webdriver:start -# in another terminal -npm run e2e:live -``` - -# Configuration -Configuration files live in `config/` we are currently using webpack, karma, and protractor for different stages of your application - -# Contributing -You can include more examples as components but they must introduce a new concept such as `Home` component (separate folders), and Todo (services). I'll accept pretty much everything so feel free to open a Pull-Request - -# TypeScript -> To take full advantage of TypeScript with autocomplete you would have to install it globally and use an editor with the correct TypeScript plugins. - -## Use latest TypeScript compiler -TypeScript 1.7.x includes everything you need. Make sure to upgrade, even if you installed TypeScript previously. - -``` -npm install --global typescript -``` - -## Use a TypeScript-aware editor -We have good experience using these editors: - -* [Visual Studio Code](https://code.visualstudio.com/) -* [Webstorm 10](https://www.jetbrains.com/webstorm/download/) -* [Atom](https://atom.io/) with [TypeScript plugin](https://atom.io/packages/atom-typescript) -* [Sublime Text](http://www.sublimetext.com/3) with [Typescript-Sublime-Plugin](https://github.com/Microsoft/Typescript-Sublime-plugin#installation) - -# Typings -> When you include a module that doesn't include Type Definitions inside of the module you need to include external Type Definitions with Typings - -## Use latest Typings module -``` -npm install --global typings -``` - -## Custom Type Definitions -When including 3rd party modules you also need to include the type definition for the module -if they don't provide one within the module. You can try to install it with typings - -``` -typings install node --save -``` - -If you can't find the type definition in the registry we can make an ambient definition in -this file for now. For example - -```typescript -declare module "my-module" { - export function doesSomething(value: string): string; -} -``` - - -If you're prototyping and you will fix the types later you can also declare it as type any - -```typescript -declare var assert: any; -``` - -If you're importing a module that uses Node.js modules which are CommonJS you need to import as - -```typescript -import * as _ from 'lodash'; -``` - -You can include your type definitions in this file until you create one for the typings registry -see [typings/registry](https://github.com/typings/registry) - -# Frequently asked questions -* What's the current browser support for Angular 2 Beta? - * Please view the updated list of [browser support for Angular 2](https://github.com/angularclass/awesome-angular2#current-browser-support-for-angular-2) -* Why is my service, aka provider, is not injecting parameter correctly? - * Please use `@Injectable()` for your service for typescript to correctly attach the metadata (this is a TypeScript problem) -* How do I run protractor with node 0.12.x? - * please check out this repo to use the old version of protractor [#146](https://github.com/AngularClass/angular2-webpack-starter/pull/146/files) -* Where do I write my tests? - * You can write your tests next to your component files. See [`/src/app/home/home.spec.ts`](/src/app/home/home.spec.ts) -* How do I start the app when I get `EACCES` and `EADDRINUSE` errors? - * The `EADDRINUSE` error means the port `3000` is currently being used and `EACCES` is lack of permission for webpack to build files to `./dist/` -* How to use `sass` for css? - * `loaders: ['raw-loader','sass-loader']` and `@Component({ styles: [ require('./filename.scss') ] })` see issue [#136](https://github.com/AngularClass/angular2-webpack-starter/issues/136) -* How do I test a Service? - * See issue [#130](https://github.com/AngularClass/angular2-webpack-starter/issues/130#issuecomment-158872648) -* How do I add `vscode-chrome-debug` support? - * The VS Code chrome debug extension support can be done via `launch.json` see issue [#144](https://github.com/AngularClass/angular2-webpack-starter/issues/144#issuecomment-164063790) -* How do I make the repo work in a virtual machine? - * You need to use `0.0.0.0` so revert these changes [#205](https://github.com/AngularClass/angular2-webpack-starter/pull/205/files) -* What are the naming conventions for Angular 2? - * please see issue [#185](https://github.com/AngularClass/angular2-webpack-starter/issues/185) and PR [196](https://github.com/AngularClass/angular2-webpack-starter/pull/196) -* How do I include bootstrap or jQuery? - * please see issue [#215](https://github.com/AngularClass/angular2-webpack-starter/issues/215) and [#214](https://github.com/AngularClass/angular2-webpack-starter/issues/214#event-511768416) -* I'm getting an error about not finding my module that I installed? - * please see [How to include or create custom type definitions](https://github.com/AngularClass/angular2-webpack-starter/wiki/How-to-include-or-create-custom-type-definitions) and [custom-typings.d.ts](https://github.com/AngularClass/angular2-webpack-starter/blob/master/src/custom-typings.d.ts) -* How do I async load a component? - * see wiki [How-do-I-async-load-a-component-with-AsyncRoute](https://github.com/AngularClass/angular2-webpack-starter/wiki/How-do-I-async-load-a-component-with-AsyncRoute) -* Error: Cannot find module 'tapable' - * Remove `node_modules/` and run `npm cache clean` then `npm install` -* What about Webpack 2? - * If you're looking for Webpack 2 version then see the [experimental version](https://github.com/gdi2290/angular2-webpack2-starter) that will be merged soon. -* How do I turn on Hot Module Replacement - * Run `npm run server:dev:hmr` -* `RangeError: Maximum call stack size exceeded` - * This is a problem with minifying Angular 2 and it's recent JIT templates. If you set `mangle` to `false` then you should be good. -* Why is the size of my app larger in development? - * We are using inline source-maps and hot module replacement which will increase the bundle size. -* If you're in China - * check out https://github.com/cnpm/cnpm - -# Support, Questions, or Feedback -> Contact us anytime for anything about this repo or Angular 2 - -* [Chat: AngularClass.slack](http://angularclass.com/member-join/) -* [Twitter: @AngularClass](https://twitter.com/AngularClass) -* [Gitter: AngularClass/angular2-webpack-starter](https://gitter.im/angularclass/angular2-webpack-starter) - -# Quick Start Guides - -## Nitrous - -You can quickly create a free development environment to get started using this -starter kit in the cloud on [Nitrous](https://www.nitrous.io/): - - - Nitrous Quickstart - - -Simply run `HOST=0.0.0.0 npm start` from the terminal inside of -`~/code/angular2-webpack-starter` and access your site via the "Preview > 3000" -link in the IDE. -___ - -enjoy — **AngularClass** - -

- -[![AngularClass](https://cloud.githubusercontent.com/assets/1016365/9863770/cb0620fc-5af7-11e5-89df-d4b0b2cdfc43.png "Angular Class")](https://angularclass.com) -##[AngularClass](https://angularclass.com) -> Learn AngularJS, Angular 2, and Modern Web Development from the best. -> Looking for corporate Angular training, want to host us, or Angular consulting? patrick@angularclass.com - -# License - [MIT](/LICENSE) +We're always happy to hear your feedback.