{"id":13493727,"url":"https://github.com/robisim74/angular-library-starter","last_synced_at":"2025-03-28T12:32:18.285Z","repository":{"id":49243752,"uuid":"80990644","full_name":"robisim74/angular-library-starter","owner":"robisim74","description":"Build an Angular library compatible with AoT compilation and Tree shaking like an official package","archived":true,"fork":false,"pushed_at":"2021-06-22T06:50:30.000Z","size":486,"stargazers_count":268,"open_issues_count":1,"forks_count":57,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-21T11:11:49.154Z","etag":null,"topics":["angular","aot-compilation","library","tree-shaking","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robisim74.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-05T12:15:11.000Z","updated_at":"2025-02-04T10:43:47.000Z","dependencies_parsed_at":"2022-09-03T12:12:39.596Z","dependency_job_id":null,"html_url":"https://github.com/robisim74/angular-library-starter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robisim74%2Fangular-library-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robisim74%2Fangular-library-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robisim74%2Fangular-library-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robisim74%2Fangular-library-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robisim74","download_url":"https://codeload.github.com/robisim74/angular-library-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246030662,"owners_count":20712415,"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":["angular","aot-compilation","library","tree-shaking","typescript"],"created_at":"2024-07-31T19:01:18.186Z","updated_at":"2025-03-28T12:32:13.276Z","avatar_url":"https://github.com/robisim74.png","language":"JavaScript","readme":"# angular-library-starter\n[![Build Status](https://travis-ci.org/robisim74/angular-library-starter.svg?branch=master)](https://travis-ci.org/robisim74/angular-library-starter)\n\u003eBuild an Angular library compatible with AoT compilation \u0026amp; Tree shaking like an official package.\n\nThis starter allows you to create a library for **Angular** apps. \nThe project is based on the official _Angular_ packages.\n\nGet the [Changelog](https://github.com/robisim74/angular-library-starter/blob/master/CHANGELOG.md).\n\n## Contents\n* [1 Project structure](#1)\n* [2 Customizing](#2)\n* [3 Testing](#3)\n* [4 Building](#4)\n* [5 Publishing](#5)\n* [6 Documentation](#6)\n* [7 Using the library](#7)\n* [8 What it is important to know](#8)\n* [9 Inlining of templates and stylesheets](#9)\n* [Built with this starter](#built-with-this-starter)\n* [Previous versions](#previous-versions)\n\n## \u003ca name=\"1\"\u003e\u003c/a\u003e1 Project structure\n- Library:\n    - **src** folder for the classes\n    - **public_api.ts** entry point for all public APIs of the package\n    - **package.json** _npm_ options\n    - **rollup.config.js** _Rollup_ configuration for building the _umd_ bundles\n    - **rollup.es.config.js** _Rollup_ configuration for building the _es2015_ bundles\n    - **tsconfig-build.json** _ngc_ compiler options for _AoT compilation_\n    - **build.js** building process using _ShellJS_\n- Testing:\n    - **tests** folder for unit \u0026 integration tests\n    - **karma.conf.js** _Karma_ configuration that uses _webpack_ to build the tests\n    - **spec.bundle.js** defines the files used by _webpack_\n- Extra:\n    - **tslint.json**  _Angular TSLint Preset_ (_TypeScript_ linter rules with _Codelyzer_)\n    - **travis.yml** _Travis CI_ configuration\n\n## \u003ca name=\"2\"\u003e\u003c/a\u003e2 Customizing\n1. Update [Node \u0026 npm](https://docs.npmjs.com/getting-started/installing-node).\n\n2. Rename `angular-library-starter` and `angularLibraryStarter` everywhere to `my-library` and `myLibrary`.\n\n3. Customize the `license-banner.txt` file with your library license.\n\n3. Update in `package.json` file:\n    - version: [Semantic Versioning](http://semver.org/)\n    - description\n    - urls\n    - packages (optional): make sure you use a version of _TypeScript_ compatible with _Angular Compiler_\n\n    and run `npm install`.\n\n4. Create your classes in `src` folder, and export public classes in `my-library.ts`.\n\n5. You can create only one _module_ for the whole library: \nI suggest you create different _modules_ for different functions, \nso that the host app can only import the modules it uses, and optimize its _Tree shaking_.\n\n6. Update in `rollup.config.js` file `globals` external dependencies with those that actually you use to build the _umd_ bundle.\n\n7. Create unit \u0026 integration tests in `tests` folder, or unit tests next to the things they test in `src` folder, always using `.spec.ts` extension.\n\n## \u003ca name=\"3\"\u003e\u003c/a\u003e3 Testing\nThe following command runs unit \u0026 integration tests that are in the `tests` folder (you can change the folder in `spec.bundle.js` file): \n```Shell\nnpm test \n```\nor in watch mode:\n```Shell\nnpm run test:watch\n```\nIt also reports coverage using _Istanbul_.\n\n## \u003ca name=\"4\"\u003e\u003c/a\u003e4 Building\nThe following command:\n```Shell\nnpm run build\n```\n- starts _TSLint_ with _Codelyzer_ using _Angular TSLint Preset_\n- starts _AoT compilation_ using _ngc_ compiler\n- creates `dist` folder with all the files of distribution, following _Angular Package Format (APF)_:\n```\n└── dist\n    ├── bundles\n    |   ├── my-library.umd.js\n    |   ├── my-library.umd.js.map\n    |   ├── my-library.umd.min.js\n    |   └── my-library.umd.min.js.map\n    ├── esm5\n    |   ├── **/*.js\n    |   └── **/*.js.map\n    ├── esm2015\n    |   ├── **/*.js\n    |   └── **/*.js.map\n    ├── fesm5\n    |   ├── my-library.js\n    |   └── my-library.js.map\n    ├── fesm2015\n    |   ├── my-library.js\n    |   └── my-library.js.map\n    ├── src\n    |   └── **/*.d.ts\n    ├── my-library.d.ts\n    ├── my-library.metadata.json\n    ├── LICENSE\n    ├── package.json\n    ├── public_api.d.ts\n    └── README\n```\nTo test locally the npm package before publishing:\n```Shell\nnpm run pack:lib\n```\nThen you can install it in an app to test it:\n```Shell\nnpm install [path]my-library-{version}.tgz\n```\n\n## \u003ca name=\"5\"\u003e\u003c/a\u003e5 Publishing\nBefore publishing the first time:\n- you can register your library on [Travis CI](https://travis-ci.org/): you have already configured `.travis.yml` file\n- you must have a user on the _npm_ registry: [Publishing npm packages](https://docs.npmjs.com/getting-started/publishing-npm-packages)\n\n```Shell\nnpm run publish:lib\n```\n\n## \u003ca name=\"6\"\u003e\u003c/a\u003e6 Documentation\nTo generate the documentation, this starter uses [compodoc](https://github.com/compodoc/compodoc):\n```Shell\nnpm run compodoc\nnpm run compodoc:serve \n```\n\n## \u003ca name=\"7\"\u003e\u003c/a\u003e7 Using the library\n### Installing\n```Shell\nnpm install my-library --save \n```\n### Loading\n#### Angular-CLI\nNo need to set up anything, just import it in your code.\n#### Rollup or webpack\nNo need to set up anything, just import it in your code.\n#### Using SystemJS configuration\n```JavaScript\nSystem.config({\n    map: {\n        'my-library': 'node_modules/my-library/bundles/my-library.umd.js'\n    }\n});\n```\n#### Plain JavaScript\nInclude the `umd` bundle in your `index.html`:\n```Html\n\u003cscript src=\"node_modules/my-library/bundles/my-library.umd.js\"\u003e\u003c/script\u003e\n```\nand use global `ng.myLibrary` namespace.\n\n### AoT compilation\nThe library is compatible with _AoT \u0026 Ivy_.\n\n## \u003ca name=\"8\"\u003e\u003c/a\u003e8 What it is important to know\n1. `package.json`\n\n    * `\"main\": \"./bundles/angular-library-starter.umd.js\"` legacy module format \n    * `\"module\": \"./esm5/angular-library-starter.js\"` flat _ES_ module, for using module bundlers such as _Rollup_ or _webpack_\n    * `\"es2015\": \"./esm2015/angular-library-starter.js\"` _ES2015_ flat _ESM_ format\n    * `\"typings\"` declaration files for _TypeScript_ compiler\n    * `\"peerDependencies\"` the packages and their versions required by the library when it will be installed\n\n2. `tsconfig.json` file used by _TypeScript_ compiler\n\n    * Compiler options:\n        * `\"strict\": true` enables _TypeScript_ `strict` master option\n\n3. `tsconfig-build.json` file used by _ngc_ compiler\n\n    * Compiler options:\n        * `\"declaration\": true` to emit _TypeScript_ declaration files\n        * `\"module\": \"es2015\"` \u0026 `\"target\": \"es2015\"` are used by _Rollup_ to create the _ES2015_ bundle\n\n    * Angular Compiler Options:\n        * `\"enableResourceInlining\": true` inlining of templates \u0026 styles\n        * `\"skipTemplateCodegen\": true` skips generating _AoT_ files\n        * `\"strictMetadataEmit\": true` without emitting metadata files, the library will not be compatible with _AoT compilation_: it is intended to report syntax errors immediately rather than produce a _.metadata.json_ file with errors\n        * `\"flatModuleId\": \"@scope/package\"` full package name has to include scope as well, otherwise AOT compilation will fail in the consumed application\n        * `\"enableIvy\": false` libraries don't need to enable Ivy\n\n4. `rollup.config.js` file used by _Rollup_\n\n    * `format: 'umd'` the _Universal Module Definition_ pattern is used by _Angular_ for its bundles\n    * `moduleName: 'ng.angularLibraryStarter'` defines the global namespace used by _JavaScript_ apps\n    * `external` \u0026 `globals` declare the external packages\n\n5. Server Side Rendering\n\n    If you want the library will be compatible with Server Side Rendering:\n    * `window`, `document`, `navigator` and other browser types do not exist on the server\n    * don't manipulate the _nativeElement_ directly\n\n## \u003ca name=\"9\"\u003e\u003c/a\u003e9 Inlining of templates and stylesheets\nNow _ngc_ compiler supports inlining of templates \u0026 styles. Moreover, this starter allows you to use `.scss` _sass_ files. If you need, you can use different pre-processors.\n\n## \u003ca name=\"built-with-this-starter\"\u003e\u003c/a\u003eBuilt with this starter\n- [angular-auth-oidc-client](https://github.com/damienbod/angular-auth-oidc-client) *An OpenID Connect Implicit Flow client for Angular*\n- [ngx-infinite-scroll](https://github.com/orizens/ngx-infinite-scroll) *An infinite scroll directive for Angular compatible with AoT compilation and Tree shaking*\n- [ngx-typeahead](https://github.com/orizens/ngx-typeahead) *A simple but yet powerful typeahead component for Angular*\n- [ng2-youtube-player](https://github.com/orizens/ng2-youtube-player) *A Powerful Youtube Player Component for Angular*\n- [ng2-completer](https://github.com/oferh/ng2-completer) *Angular autocomplete component*\n- [ngx-store](https://github.com/zoomsphere/ngx-store) *Angular Storage library for managing `localStorage`, `sessionStorage` and cookies, allowing to watch storage changes. Includes easy-to-use decorators, services and API based on builder pattern.*\n- [ngx-table-editor](https://github.com/maurei/ngx-table-editor) *A library for Angular that transforms HTML tables into dynamic editable components.*\n- [ngx-ui-scroll](https://github.com/dhilt/ngx-ui-scroll) *An Angular `*ngFor`-like directive for infinite/virtual scrolling*\n\n## \u003ca name=\"previous-versions\"\u003e\u003c/a\u003ePrevious versions\n- **Angular v8**\n    - [Branch](https://github.com/robisim74/angular-library-starter/tree/angular_v8)\n\n- **Angular v7**\n    - [Branch](https://github.com/robisim74/angular-library-starter/tree/angular_v7)\n\n- **Angular v6**\n    - [Branch](https://github.com/robisim74/angular-library-starter/tree/angular_v6)\n\n- **Angular v5**\n    - [Branch](https://github.com/robisim74/angular-library-starter/tree/angular_v5)\n\n- **Angular v4**\n    - [Branch](https://github.com/robisim74/angular-library-starter/tree/angular_v4)\n\n- **Angular v2**\n    - [Branch](https://github.com/robisim74/angular-library-starter/tree/angular_v2)\n\n## License\nMIT\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobisim74%2Fangular-library-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobisim74%2Fangular-library-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobisim74%2Fangular-library-starter/lists"}