# johnpapa/angular-styleguide: Opinionated Conventions for Angular 1 and Angular 2 Teams > The angular-styleguide by John Papa is a reference document covering naming conventions, file structure, and code organization patterns for Angular applications. It covers Angular 1 and Angular 2 in separate guides, each written as a rationale-driven set of rules rather than a code generator or tooling package. **johnpapa/angular-styleguide** — Angular Style Guide: A starting point for Angular development teams to provide consistency through good practices. - Repository: https://github.com/johnpapa/angular-styleguide - Website: http://johnpapa.net - Stars: 23,604 · Forks: 4,024 - Language: Vim Snippet - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/johnpapa-angular-styleguide ## What the Guide Is and Who Endorsed It The angular-styleguide is a written reference, not an installable package. It provides opinionated conventions for building Angular applications, covering syntax, file naming, folder structure, and code organization. The author is John Papa, and the README notes that Igor Minar, described as the lead on the Angular team, reviewed the guide and entrusted John Papa to maintain it. The guide covers Angular 1 and Angular 2 in separate sections, each in its own subdirectory of the repository. The Angular 1 guide is at a1/README.md and the Angular 2 guide is at a2/README.md. The top-level README.md points to both without duplicating content from either. ## How the Repository Is Structured The top-level entries in the repository are: .github/, AGENTS.md, LICENSE, README.md, a1/, and a2/. The actual style guide content lives inside a1/ and a2/ as separate README.md files. This organization means the two guides are maintained independently. The a1/ guide covers Angular 1 (AngularJS), the framework that predates Angular 2's complete rewrite. The a2/ guide covers the rewritten framework. Readers looking for Angular 2 conventions should navigate directly to a2/README.md, not the root. The repository has no releases and no versioning scheme. The primary language is listed as Vim Snippet, which reflects snippet files included for editor tooling rather than the guide content itself. The last push was on 2026-04-30. ## The Core Purpose: Rationale, Not Just Rules The README describes the guide's purpose as providing guidance on building Angular applications by showing the conventions used and, more importantly, why those conventions were chosen. This sets it apart from a linter configuration or a code generator. Each rule in the guide explains the reasoning behind it. The README credits Ward Bell as a significant influence, noting that many of the styles developed through pair programming sessions. The guide also references John Papa's Pluralsight training course Angular Patterns: Clean Code as a companion resource, though the style guide itself is standalone and freely available in the repository. The stated goal is to give teams a common baseline so that developers joining a project can read existing code without needing to ask about naming decisions or file layout. ## What the Angular 1 Guide Covers The a1/README.md is the original and more complete guide. Angular 1 (AngularJS) was the version in widespread use when the guide was first published. The guide covers areas specific to AngularJS's architecture: controllers, services, factories, directives, filters, and module structure. The guide addresses the AngularJS patterns that caused maintenance problems in large codebases, such as the use of $scope versus the controller-as syntax, how to name and organize files so a developer can find them by feature rather than by type, and how to avoid global state in factories and services. The README does not reproduce the content of a1/README.md at the top level; you navigate to that file to read the actual rules. ## What the Angular 2 Guide Covers and Its Limitations The a2/README.md covers the Angular 2 framework, which introduced TypeScript as the primary language, a component-based architecture, and a module system distinct from AngularJS's dependency injection model. Angular 2 was the starting point for the current Angular framework, but the Angular project has released many major versions since Angular 2. Practices for standalone components, signals, and the new control flow syntax introduced in later versions are not part of this guide. The README does not state which Angular versions the a2/ guide applies to, nor does it reference the official Angular documentation. For teams using Angular 17 or later, the official Angular documentation at angular.dev publishes its own style guide. The johnpapa guide predates several major architectural changes and teams should treat a2/ as a historical baseline rather than a current specification. ## Using the Guide: No Install, Just Read and Adopt Because the guide is a Markdown document, using it means reading it and agreeing as a team on which rules to adopt. There is no CLI tool, no scaffolding command, and no linter plugin that enforces the guide's rules automatically. The repository does include Vim snippet files, referenced by the primary language listing of Vim Snippet in the repository metadata. These are editor snippets for developers using Vim who want to generate Angular boilerplate matching the guide's conventions. The README does not mention snippets for other editors. Contributing to the guide follows a three-step process: open a GitHub issue to discuss the change, open a pull request that references the issue and explains the change and its value, and await review. The README notes that GitHub issues and pull requests are searchable through Google, which was part of the motivation for using GitHub as the documentation platform. ## Maintenance Status and License The last push was on 2026-04-30. The repository has no releases and no changelog file in the top-level directory. The guide does not include a version number, so there is no way to tell at a glance which version of the Angular 1 or Angular 2 conventions it reflects without reading the git history. The license is MIT, which permits use, modification, and redistribution. The copyright notice in the LICENSE file reads 2014-2016, which reflects the original authoring period. The README instructs contributors that by submitting content they agree to make it available under the same license. The repository includes an AGENTS.md file at the top level alongside the main README.md. The guide carries the ai-ready badge mentioned in the README, suggesting it has been prepared for AI tooling use. The README does not describe what that preparation entails beyond the badge reference. ## Conclusion This guide is the right starting point for an Angular team that wants to agree on conventions before a project grows. It is not the right tool for Angular 17 or later, where the Angular team publishes its own official style guide. Before using it, check the Angular version your project targets and compare the johnpapa guide with the current Angular documentation, since practices around standalone components and signals are not covered here. ## FAQ ### What is the purpose of the johnpapa Angular style guide? The guide provides opinionated naming conventions, file structure patterns, and code organization rules for Angular applications. The README states the goal is to explain not just the conventions but the reasons behind them, so teams can make informed decisions rather than following rules blindly. ### What is Angular and why is it used? The guide does not describe Angular itself beyond naming it as the framework its conventions apply to. It covers Angular 1 (AngularJS) in the a1/ directory and Angular 2 in the a2/ directory. The README references John Papa's Pluralsight course Angular Patterns: Clean Code as background material. ### Does the angular-styleguide cover the latest Angular versions? The guide covers Angular 1 and Angular 2. It does not cover standalone components, signals, or the control flow syntax introduced in Angular 17 and later. Teams using recent Angular versions should compare this guide with the official Angular documentation at angular.dev. ### Does the angular-styleguide come with a linter or CLI tool? No. The guide is a Markdown document, not an installable package. It includes Vim editor snippets for boilerplate generation, but there is no CLI, no scaffolding command, and no linter plugin that automatically enforces its rules. ## Sources - [Issues](https://github.com/johnpapa/angular-styleguide/issues) - [johnpapa/angular-styleguide on GitHub](https://github.com/johnpapa/angular-styleguide) - [License: MIT](https://github.com/johnpapa/angular-styleguide/blob/main/LICENSE) - [Project website](http://johnpapa.net) - [README](https://github.com/johnpapa/angular-styleguide/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/johnpapa-angular-styleguide