diff --git a/README.md b/README.md index a6f1e48..8719051 100644 --- a/README.md +++ b/README.md @@ -5,17 +5,20 @@ If you want to create an Angular library with directives, services and/or pipes, then this generator is just what you need. -The generator: +This generator aligns with the [official Angular Package Format](https://goo.gl/AMOU5G) and automatically generates a [Flat ES Module](http://angularjs.blogspot.be/2017/03/angular-400-now-available.html), a single metadata.json and type definitions to make your library ready for AOT compilation by the consuming Angular application. -- creates and configures `package.json` for your library -- creates and configures `tsconfig.json` for your library -- creates and configures `tslint.json` for your library +Watch [Jason Aden's talk](https://www.youtube.com/watch?v=unICbsPGFIA) to learn more about the Angular Package Format. + +More specifically, this generator: + +- creates and configures `package.json` for the development of your library +- creates and configures a second `package.json` for the distribution of your library +- creates and configures `tsconfig.json` for your editor during development +- creates and configures `tslint.json` for linting purposes - creates and configures `.gitignore`, `.npmignore` and `.travis.yml` -- creates the main library file -- creates a sample directive, component, service and pipe -- creates a default export for future compatibility with angular cli, see this [discussion for more](https://github.com/angular/angular-cli/issues/96) +- creates the main library file, a sample directive, a sample component, a sample service and a sample pipe - configures [tslint](https://palantir.github.io/tslint/) for you with [codelyzer](https://github.com/mgechev/codelyzer) support -- supports [@types](https://www.npmjs.com/~types) +- creates and configures build scripts to generate type definitions and metadata files to make library ready for AOT compilation This generator is built for Angular version 2 and above, hence the name generator-angular2-library. If you are looking for a similar generator for AngularJS 1.x, please visit [generator-angularjs-library](https://github.com/jvandemo/generator-angularjs-library). @@ -57,27 +60,29 @@ and create the following files for you: ```bash . ├── README.MD -├── index.ts +├── build.sh ├── package.json ├── src +│   ├── index.ts +│   ├── package.json │   ├── sample.component.ts │   ├── sample.directive.ts │   ├── sample.pipe.ts -│   └── sample.service.ts +│   ├── sample.service.ts +│   └── tsconfig.es5.json ├── tsconfig.json -├── tslint.json -└── typings.json +└── tslint.json ``` You can then add or edit `*.ts` files in the `src/` directory and run: ```bash -$ npm run tsc +$ npm run build ``` -to automatically create all `*.js`, `*.js.map` and `*.d.ts` files in the `dist/` directory. +to automatically create all `*.js`, `*.d.ts` and `*.metadata.json` files in the `dist/` directory. -## Tslint +## Linting your code Everything comes pre-configured with tslint and codelyzer support. To lint your code: @@ -85,6 +90,35 @@ Everything comes pre-configured with tslint and codelyzer support. To lint your $ npm run lint ``` +## Building your library + +From the root of your library directory, run: + +```bash +$ npm run build +``` + +This will generate a `dist` directory with: + +- a `package.json` file specifically for distribution with Angular listed in the `peerDependencies` +- `sample-library.js`: a Flat ES Module (FESM) file that contains all your library code in a single file +- `*.d.ts`: type definitions for you library +- `sample-library.metadata.json`: metadata for your library to support AOT compilation + +## Publishing your library to NPM + +To publish your library to NPM, first generate the `dist` directory: + +```bash +$ npm run build +``` + +and then publish the contents of the `dist` directory to NPM: + +```bash +$ npm publish dist +``` + ## Consuming your library Once you have published your library to the NPM registry, you can import it in any Angular application by first installing it using NPM: @@ -170,11 +204,12 @@ To consume your library before you publish it to npm, you can follow the followi 3. Compile your library files: ``` - $ npm run tsc + $ npm run build ``` -4. From the `sample-library` directory, create a symlink in the global node_modules directory to this library: +4. From the `sample-library/dist` directory, create a symlink in the global node_modules directory to the `dist` directory of your library: ``` + $ cd dist $ npm link ``` @@ -254,10 +289,9 @@ To consume your library before you publish it to npm, you can follow the followi 10. When you make a change to your library, recompile your library files again from your `sample-library` directory: ``` - $ npm run tsc - ``` + $ npm run build + ``` - ## To do - Create process for running unit tests @@ -280,6 +314,11 @@ MIT © [Jurgen Van de Moere](http://www.jvandemo.com) ## Change log +### v8.0.0 + +- Update build process +- Add support for AOT compilation + ### v7.0.0 - Update to Angular 4 diff --git a/generators/app/index.js b/generators/app/index.js index 24dd23a..7b99261 100644 --- a/generators/app/index.js +++ b/generators/app/index.js @@ -101,12 +101,6 @@ module.exports = class extends Generator { this.destinationPath('.travis.yml') ); - // Copy src folder - this.fs.copy( - this.templatePath('src/**/*'), - this.destinationPath('src') - ); - // Copy tsconfig.json this.fs.copyTpl( this.templatePath('_tsconfig.json'), @@ -143,10 +137,34 @@ module.exports = class extends Generator { } ); - // Copy index.ts + // Copy build.sh + this.fs.copyTpl( + this.templatePath('build.sh'), + this.destinationPath('build.sh'), + { + props: this.props + } + ); + + // Copy src folder + this.fs.copy( + this.templatePath('src/**/*.ts'), + this.destinationPath('src') + ); + + // Copy src/package.json + this.fs.copyTpl( + this.templatePath('src/_package.json'), + this.destinationPath('src/package.json'), + { + props: this.props + } + ); + + // Copy src/tsconfig.es5.json this.fs.copyTpl( - this.templatePath('index.ts'), - this.destinationPath('index.ts'), + this.templatePath('src/_tsconfig.es5.json'), + this.destinationPath('src/tsconfig.es5.json'), { props: this.props } diff --git a/generators/app/templates/README.MD b/generators/app/templates/README.MD index 15c4121..ef56be5 100644 --- a/generators/app/templates/README.MD +++ b/generators/app/templates/README.MD @@ -55,10 +55,10 @@ Once your library is imported, you can use its components, directives and pipes ## Development -To generate all `*.js`, `*.js.map` and `*.d.ts` files: +To generate all `*.js`, `*.d.ts` and `*.metadata.json` files: ```bash -$ npm run tsc +$ npm run build ``` To lint all `*.ts` files: diff --git a/generators/app/templates/_package.json b/generators/app/templates/_package.json index 13c4fba..1730c75 100644 --- a/generators/app/templates/_package.json +++ b/generators/app/templates/_package.json @@ -2,11 +2,10 @@ "name": "<%= props.libraryName.kebabCase %>", "version": "0.1.0", "scripts": { - "build": "ngc -p tsconfig.json", + "build": "./build.sh", "lint": "tslint --type-check --project tsconfig.json src/**/*.ts", "test": "tsc && karma start", - "prepublish": "tsc", - "tsc": "tsc" + "prepublish": "echo \"Publish aborted: please run 'npm publish' from the dist directory\" && exit 1" }, "repository": { "type": "git", @@ -23,9 +22,6 @@ "bugs": { "url": "<%= props.gitRepositoryUrl %>/issues" }, - "main": "./dist/index.js", - "dependencies": { - }, "devDependencies": { "@angular/common": "^4.0.0", "@angular/compiler": "^4.0.0", @@ -42,10 +38,11 @@ "karma": "~1.4.1", "karma-chrome-launcher": "~2.0.0", "karma-cli": "~1.0.1", + "karma-coverage-istanbul-reporter": "^0.2.0", "karma-jasmine": "~1.1.0", "karma-jasmine-html-reporter": "^0.2.2", - "karma-coverage-istanbul-reporter": "^0.2.0", "protractor": "~5.1.0", + "rollup": "^0.41.6", "rxjs": "^5.1.0", "ts-node": "~2.0.0", "tslint": "~4.5.0", diff --git a/generators/app/templates/_tsconfig.json b/generators/app/templates/_tsconfig.json index fe9c8aa..5a3672e 100644 --- a/generators/app/templates/_tsconfig.json +++ b/generators/app/templates/_tsconfig.json @@ -1,25 +1,17 @@ +// This file is only used to configure the editor during development. +// It is NOT used for building the library. { "compilerOptions": { - "noImplicitAny": true, - "module": "commonjs", - "target": "ES6", - "emitDecoratorMetadata": true, + "baseUrl": "./src", "experimentalDecorators": true, - "allowUnusedLabels": false, - "noImplicitReturns": true, - "sourceMap": true, - "declaration": true, - "outDir": "./dist", - "typeRoots": [ - "node_modules/@types" - ] - }, - "exclude": [ - "node_modules", - "dist", - "**/*.spec.ts" - ], - "angularCompilerOptions": { - "strictMetadataEmit": true + "moduleResolution": "node", + "rootDir": "./src", + "lib": [ + "es2015", + "dom" + ], + "skipLibCheck": true, + // Don't auto-discover @types/node, it results in a ///", + "version": "0.1.0", + "repository": { + "type": "git", + "url": "<%= props.gitRepositoryUrl %>" + }, + "author": { + "name": "<%= props.author.name %>", + "email": "<%= props.author.email %>" + }, + "keywords": [ + "angular" + ], + "license": "MIT", + "bugs": { + "url": "<%= props.gitRepositoryUrl %>/issues" + }, + "module": "<%= props.libraryName.kebabCase %>.js", + "typings": "<%= props.libraryName.kebabCase %>.d.ts", + "peerDependencies": { + "@angular/core": "^4.0.0", + "rxjs": "^5.1.0", + "zone.js": "^0.8.4" + } +} diff --git a/generators/app/templates/src/_tsconfig.es5.json b/generators/app/templates/src/_tsconfig.es5.json new file mode 100644 index 0000000..16d797f --- /dev/null +++ b/generators/app/templates/src/_tsconfig.es5.json @@ -0,0 +1,32 @@ +// This file is used by ngc to create the files in the build directory +{ + "compilerOptions": { + "declaration": true, + "module": "es2015", + "target": "es5", + "baseUrl": ".", + "stripInternal": true, + "emitDecoratorMetadata": true, + "experimentalDecorators": true, + "moduleResolution": "node", + "outDir": "../build", + "rootDir": ".", + "lib": [ + "es2015", + "dom" + ], + "skipLibCheck": true, + // Don't auto-discover @types/node, it results in a ///.js", + "flatModuleId": "<%= props.libraryName.kebabCase %>" + }, + "files": [ + "./index.ts" + ] +} diff --git a/generators/app/templates/index.ts b/generators/app/templates/src/index.ts similarity index 56% rename from generators/app/templates/index.ts rename to generators/app/templates/src/index.ts index 192d071..1fc1e6a 100644 --- a/generators/app/templates/index.ts +++ b/generators/app/templates/src/index.ts @@ -1,14 +1,14 @@ import { NgModule, ModuleWithProviders } from '@angular/core'; import { CommonModule } from '@angular/common'; -import { SampleComponent } from './src/sample.component'; -import { SampleDirective } from './src/sample.directive'; -import { SamplePipe } from './src/sample.pipe'; -import { SampleService } from './src/sample.service'; +import { SampleComponent } from './sample.component'; +import { SampleDirective } from './sample.directive'; +import { SamplePipe } from './sample.pipe'; +import { SampleService } from './sample.service'; -export * from './src/sample.component'; -export * from './src/sample.directive'; -export * from './src/sample.pipe'; -export * from './src/sample.service'; +export * from './sample.component'; +export * from './sample.directive'; +export * from './sample.pipe'; +export * from './sample.service'; @NgModule({ imports: [ diff --git a/package.json b/package.json index 2aa069d..b2b690a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "generator-angular2-library", - "version": "7.0.0", + "version": "8.0.0", "description": "Generator to create an Angular 2 library", "homepage": "https://github.com/jvandemo/generator-angular2-library", "author": {