Angular 1 TypeScript Scaffold

The de facto starter repo for building scalable and Angular 2 migration ready apps with Angular, Typescript 2.x, ng-metadata and Webpack 1.x

This seed repo serves as a minimal starter for anyone looking to get up and running with Angular 1 and Typescript fast. It uses Webpack for the build process, which is highly maintainable, fast and modular build system.

Features:

• un-opinionated directory/file structure ( we recommend to follow Angular 2 styleguide )
• Ready to go build system using Webpack for working with TypeScript
• great Angular 1 seed repo for anyone who wants to start their project and be ready for migration to Angular 2.
• Angular code powered by ng-metadata which allows you to write angular 2 ready code with angular 1
• includes TSlint and Codelyzer so it will tell you if your code is not following Angular 2 styleguide
• testing Angular code with Jasmine and Karma.
• coverage with Istanbul and Karma
• type manager with npm ( via @types
• Sass support ( you can add your own preprocessor pretty easily )
• source maps support
• Component Router ( for this we have separate branch, because we don't want to force you to use it ;) ) NOTE this is deprecated since angular team dropped router support to ng1
• ngUpgrade + Angular 2 integration within build

Install

# clone our repo
# --depth 1 removes all but one .git commit history
git clone --depth=1 https://github.com/ngParty/Angular1-scaffold.git <your-project-name>

# change directory to our repo
cd <your-project-name>

# install all dependencies locally ( global is evil ! )
npm install

Start Development

# start the server, webpack ( which runs Typescript compilation and linting with TSlint and Codelyzer )
npm start

open http://localhost:9000

Testing

# for running test once
npm test

# for running tests in watch mode
npm run test:watch

Production build

npm run build

check your production ready application within /dist

NOTE: If you need to include any assets like images, custom fonts etc. place them withing src/assets

This folder will be copied and flattened to your /dist. so as an example: /src/assets/images/hello.png -> /dist/images/hello.png

For these reasons use images/pluto-the-planet.jpg path when directly referencing assets withing your html

Adding 3rd party libraries

npm install --save <your-library-name>

If it doesn't ship with type definitions, you need to download them via npm @types

now just import what you need via es2015 module syntax

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 install it with npm:

npm install --save @types/moment

If there isn't a type definition for your 3rd party library, which is very unlikely, you can place your own custom global type definitions within src/globals.d.ts

For example:

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

declare var assert: any;

If you're importing a module that uses Node.js modules which are CommonJS you need to import as

import * as _ from 'lodash';

You can include your type definitions in this file until you create one for the @types npm registry

Proposed File structure

src/
 ├──app/                   * WebApp: folder, our source files that will be compiled to javascript
 │   │--shared/            * Do put all shared files within a component feature in a shared folder.
 |   |   |-- exception.service.ts
 |   |   |-- exception.service.spec.ts
 |   |   |-- shared.module.ts * shared module with all shared declarations and providers
 |   |   |-- index.ts             * barrel file
 │   |--app.module.ts      * angular module
 │   |--app.component.ts   * root component
 │   │──app.spec.ts        * a simple test of components in app.ts
 │   │──index.ts           * barrel file
 │   │
 │──assets/                * static assets are served here
 │   ├──icon/              * our list of icons from www.favicon-generator.org
 │   ├──images/            * our custom app images
 │   ├──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
 |──main.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
 |
 |──globals.d.ts   * our custom global type definitions

What is a barrel file ?

Code snippets

Be efficient, we have code snippets for you my friend!

Data flow and state management

We highly recommend to go fully reactive by embracing Redux or RxJs or both! From architectural point Smart and Dumb components, is the way to go!

Have fun!

Created with ❤ by ngParty team.