{"id":15093062,"url":"https://github.com/angular/angular-component-spec","last_synced_at":"2025-10-06T11:30:59.493Z","repository":{"id":8206601,"uuid":"9640159","full_name":"angular/angular-component-spec","owner":"angular","description":"Specification for reusable AngularJS components","archived":true,"fork":false,"pushed_at":"2015-05-20T13:43:48.000Z","size":201,"stargazers_count":61,"open_issues_count":2,"forks_count":21,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-09-26T11:03:24.721Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"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/angular.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-24T05:31:29.000Z","updated_at":"2024-02-26T17:13:06.000Z","dependencies_parsed_at":"2022-08-06T22:00:46.166Z","dependency_job_id":null,"html_url":"https://github.com/angular/angular-component-spec","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/angular%2Fangular-component-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angular%2Fangular-component-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angular%2Fangular-component-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angular%2Fangular-component-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angular","download_url":"https://codeload.github.com/angular/angular-component-spec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219877267,"owners_count":16554853,"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-09-25T11:03:24.143Z","updated_at":"2025-10-06T11:30:54.193Z","avatar_url":"https://github.com/angular.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Specification for reusable AngularJS components\n\n_**Attention**: This document is a **WIP**! Since we want to collect as many opinions as possible, feel free to fork and send a Pull Request.\nWe hope that once this specification is called final, developers of angular components will do things the same way, which will allow the Angular Team to provide better tooling._\n\n### Preface\nThis specification should help you as a developer, as well as a consumer of Angular components, to find, use and develop reusable Angular components.\nAngular components are distributed as Bower packages.\nSee [bower.io](http://bower.io) for more information.\n\nIt has two parts:\n\n1. [The **consumer** perspective](#angularjs-components-consumer)\n2. [The **creator/forker** perspective](#angularjs-components-creator)\n\nThe consumer perspective covers all topics on finding and using Angular components, whereas the creator or forker part gives an in-depth description of how to create, structure and publish an Angular component, as well as which naming conventions to follow for the component itself and the resulting bower package.\n\n### Dependencies\n\nThis specification also expects that needed tools are already installed and ready to use.\nWhich means the following commands should be used to install the needed tools on a local machine:\n\n**Node Package Manager**\n\nVisit [https://nodejs.org/download/](https://nodejs.org/download)\n\n**Bower Package Manager**\n```shell\n$ npm install -g bower\n```\n\n### Definitions in this specification\n\nThis specification contains expressions like _components_, _packages_ and _modules_.\nThese are the definitions:\n\n#### Component\n_Component_ is a Bower concept.\nA _component_ is a repo which contains some files for client-side use in a web browser.\nThis may include, but is not limited to, JavaScript, CSS, HTML, and images.\nA Bower _component_ has a component.json (or bower.json) file that describes the _component_ and its dependencies.\n\n#### Package\n_Package_ is a Bower concept.\nFor the time being,  one can think of the terms _package_ and _component_ as being interchangeable in the context of Bower.\nIn general, _package_ is the thing that you can download, and contains a _component_, which is a group of one or more assets.\nSaying one can think of them as interchangeable for now, is because there's a one-to-one correspondence of package to component.\n\n#### Module\nWhen the word _module_ appears, this specification means an AngularJS module.\nAn AngularJS module may have multiple directives, services, or filters.\nFor _components_, each _module_ typically has its own file.\nBower _components_ typically contain just one AngularJS _module_, though in theory there can be more.\n\n## AngularJS Components Consumer\n\n_This part of the **Reusable AngularJS components** specification is highly inspired by @btford 's [blog post](http://briantford.com/blog/angular-bower.html)._\n\n### Table Of Contents\n\n* [Naming Conventions](#naming-conventions)\n    * [Registered Angular components](#registered-angular-components)\n* [Searching and Finding](#searching-and-finding)\n    * [Search for packages](#search-for-packages)\n    * [Finding packages with keywords](#finding-packages-with-keywords)\n* [Installing packages](#installing-packages)\n    * [Installing unregistered packages](#installing-unregistered-packages)\n\n### Naming Conventions\n\n#### Registered Angular components\nTo make searching and filtering for Angular components with Bower as easy as possible, the name under which Angular components get registered should match the following pattern.\n\n```\nangular-[optional-namespace]-[thing-name]-[optional-thing-type]\n```\n\nName should be prefixed with `angular-`.\n\n##### optional-namespace\nCan be used to group similar components such as\n```\nangular-phonegap-ready\nangular-phonegap-geolocation\n```\n\n##### thing-name\nThis is the actual module name.\nIt should match the functionality of the module.\nE.g. the `geolocation` in `angular-phonegap-geolocation`.\nOr the `translate` in `angular-translate`.\n\n##### optional-thing-type\nCould be `filter`, `directive` or `service`.\nThis is for clarification if `[thing-name]` isn't enough.\n\n\n### Searching and Finding\n\n#### Search for packages\nSince registered Angular components follow a **naming convention**, finding them can be achieved by simply searching for all registered Bower packages which have an _angular_ in their registry name.\n\n```shell\n$ bower search angular\n```\nShould return a list of registered bower packages with an _angular_ in their name.\n\n#### Finding packages with keywords\nBower doesn't currently support a search with keywords.\nFiltering packages by keyboard can be done by using `bower search` in combination with the `grep` command.\nSo the following command searches for Angular packages with the keyword \"phonegap\".\n\n```shell\n$ bower search angular | grep \"phonegap\"\n```\n\n### Installing packages\nOnce the right package is found, one can install it using the Bower `install` command.\nE.g. installing AngularJS itself as a package would look like this:\n\n```shell\n$ bower install angular\n```\n\nThis will download the specified package into the folder which is configured as components folder via `.bowerrc`.\n\n#### Installing unregistered packages\nIt is possible that there's an AngularJS component on GitHub, which is not registered as bower component.\nThis could have several reasons:\n\n* The author doesn't plan to publish it as a Bower component\n* The name the author wants to register it is already been taken\n* The package is actually registered but the endpoint is broken (which unfortunately happens often, and there's currently no way to take care of that as a package maintainer.\nSee [https://github.com/twitter/bower/issues/120](https://github.com/twitter/bower/issues/120)\n\nIn that cases one can install the package by specifying the GitHub user and the repository.\nThis works for **every** GitHub repository.\n\n```shell\n$ bower install \u003cusername\u003e/\u003crepository\u003e\n```\n\n## TL;DR\n\nYour modules should be publicly distributed with this convention ('Publicly' as in bower names, repository names, website names, etc):\n```\nangular-[optional-namespace]-[thing-name]-[optional-thing-type]\n```\nExample:\n```javascript\nangular-phonegap-ready\nangular-superman-directives\n```\n\nYour angular modules in the source should have this convention:\n```\n[author-name].[thing-name].[thing-type]\n```\nExample:\n```javascript\nangular.module('btford.phonegap-ready', []);\nangular.module('doctor-evil.superman-directives.kryptonite', [])\n```\n\n\n## Bad Practices\n\nPlease don't do these things.\n\n### Registering controllers, services, filters, etc. on the `ng` module\n\n```javascript\n// this is bad\nangular.module('ng').filter('tel', function (){});\n```\n\nInstead create your own module and add it as a dependency to your application's top-level module.\n\n**Why:** this is needlessly frail. See [this issue](https://github.com/angular/angular.js/issues/7709#issuecomment-46300969).\n\n\n## References\n\n* [Kick-off discussion](https://gist.github.com/PascalPrecht/5411171)\n* [Brian's blog post](http://briantford.com/blog/angular-bower.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangular%2Fangular-component-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangular%2Fangular-component-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangular%2Fangular-component-spec/lists"}