Open-source project
johnpapa/angular-styleguide avatar
johnpapa/angular-styleguide

johnpapa/angular-styleguide: an opinionated guide for Angular 1 and Angular 2 teams

Angular Style Guide: A starting point for Angular development teams to provide consistency through good practices.

23,581 stars4,006 forksVim SnippetMIT

At a glance

What is it?
The repository splits its advice into two directories, a1/ and a2/, written for different generations of Angular. It tells you which conventions to pick and why, and the README is explicit that the choices are one developer's, not a specification.
Who is it for?
Adopt it if your team is starting an Angular 1 or Angular 2 project and wants naming and folder conventions written down before the first pull request. Do not adopt it as a modern Angular reference: the repository carries a1/ and a2/ guides, and the README does not document an Angular 3 or later edition.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly Vim Snippet, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • johnpapa/angular-styleguide23,581 ★ · -30
Star history
Repository2026-09-212026-11-15
johnpapa/angular-styleguide23.6k23.6k

-30 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What johnpapa/angular-styleguide is for, and who it is written for

This repository is a written-down set of conventions for building Angular applications. The README calls it an "Opinionated Angular style guide for teams by @john_papa" and says the styles come from the author's development experience, presentations, Pluralsight training courses and team work. The stated purpose is to show the conventions he uses and, more importantly, why he chooses them. That second half is the actual product: a rule with a reason attached is easier to argue with than a rule alone.

The audience is a development team that has to agree on something. A single developer can keep conventions in their head. Three developers cannot, and the moment a code review turns into a debate about file names, the guide is the document you point at. The README also notes that Igor Minar, lead on the Angular team, reviewed the guide and contributed feedback, and that Ward Bell influenced its evolution through pair programming sessions.

The repository does not ship a linter, a config file or a generator. It ships prose and examples. Nothing enforces a rule after you adopt it, so the guide is a shared reference rather than a build step.

Two guides in one repository: a1/ and a2/

The repository layout is the first thing to understand. The top level holds .github/, AGENTS.md, LICENSE, README.md, a1/ and a2/. The README states plainly that there are multiple versions of Angular and therefore multiple versions of the guide, and that you should choose your guide appropriately. Angular 1 readers are sent to a1/README.md and Angular 2 readers to a2/README.md.

That split is a design decision with consequences. Angular 1 and Angular 2 differ in module system, component model and dependency injection, so a naming rule that makes sense in one can be wrong in the other. Keeping both under one repository preserves the shared reasoning while letting the specifics diverge. It also means the root README is mostly a signpost. Anyone who reads only the front page gets the purpose statement and the licence, not the conventions.

The top level contains an AGENTS.md file, which is a signal that the project has thought about machine-readable instructions for contributors. The README does not describe its contents, so treat it as a contributor-facing artifact rather than part of the guide.

How to start using the guide: clone it and read the right directory

There is no package to install. The guide is Markdown in a Git repository, so the first step is getting a local copy. The README links the version guides by path, and those paths are the only concrete addresses the repository gives you.

bash
git clone https://github.com/johnpapa/angular-styleguide.git

The README points Angular 1 readers at a1/README.md and Angular 2 readers at a2/README.md, so open the one that matches your framework.

bash
cat a1/README.md

That prints the Angular 1 guide. Swap the path to a2/README.md for the Angular 2 guide. The README does not publish an npm package name, a CLI command or a configuration file, so there is nothing to add to package.json and no build integration to wire up.

The practical first use is a team review, not a code change. Read the version directory that applies to you, then pick the handful of rules your team currently violates most often and write those into your own contributing document. The repository's own contribution process is the model: the README asks contributors to discuss changes in a GitHub issue first, then open a pull request that references the issue and explains why the change adds value.

Where the guide stops being useful

The largest limitation is scope by version. The README documents an Angular 1 guide and an Angular 2 guide. It does not announce an edition for later Angular majors, and the repository layout shows no third version directory. A team on a current Angular release is reading historical advice, and the parts that survive are the general ones: naming, file organisation, how to justify a convention. The framework-specific parts are the parts most likely to have moved on.

Second, the guide is opinionated by design, and opinion is not consensus. The README is direct that these are the conventions one developer uses. That is a feature when your team has no conventions at all, and a liability when your team already has a working set and someone wants to relitigate it against a document written for a different framework generation.

Third, nothing here is enforced. There is no lint rule to fail a build, no schema to validate a file name. Adoption depends on reviewers remembering the rule. Teams that want mechanical enforcement will get nothing from this repository on that front and will need to translate the conventions into their own tooling.

Finally, the README's contribution process is issue-first, and pull requests can be declined. If your team needs a variant of a rule, you cannot simply fork the advice and expect it upstream. You can fork the repository, but the README's own process assumes discussion before change.

Angular's own style guide and what changes when you switch

The obvious alternative is the Angular team's official style guide, published alongside the framework documentation. The difference in approach is authorship and cadence. This repository is one developer's opinionated set, reviewed by an Angular team lead and shaped by pair programming, and it is organised as two frozen version directories. The official guide is maintained by the framework team and moves with the framework.

That changes what you get. The official guide will reflect current Angular APIs and will be revised when the framework changes. This repository gives you the reasoning behind a convention in the author's voice, which is often more persuasive in a code review than a rule with no explanation. It also gives you the Angular 1 material, which the official guide is unlikely to prioritise.

A second alternative is to write your own short document and skip both. That is reasonable for a small team, but it costs the thing this repository already paid for: the reasons. If you write your own, you still have to justify each rule, and the README's framing suggests that reasoning is the part that makes a style guide survive contact with a team.

The honest comparison is not which guide is better. It is which guide matches the Angular version in your package.json. If that version is 1 or 2, this repository is directly relevant. If it is later, the official guide is the one written for your framework.

Maintenance, licensing and the cost of following a moving guide

The repository is not archived, and the last push was on 2026-04-30. That is recent enough that the project is still receiving changes, but the README describes a1/ and a2/ guides, and the repository has no published GitHub releases. There is no versioned artifact to pin, which means a team that adopts the guide is adopting a moving document. If you want a fixed reference, clone it and record the commit hash you reviewed.

The upgrade cost is mostly human. When the upstream guide changes a rule, your team has to decide whether to follow, and the README's process expects that decision to happen in an issue before a pull request. There is no automated migration path, and the guide does not describe one.

Licensing is straightforward on its face. The repository is MIT licensed, and the README summarises it as "tldr; Use this guide. Attributions are appreciated." The licence text permits use, copy, modification, distribution, sublicensing and sale, provided the copyright notice and permission notice are included in copies or substantial portions. The copyright line reads "Copyright (c) 2014-2016 John Papa". The README also notes that contributing to the repository means agreeing to make your content available under the repository's licence. This is a description of the licence text, not legal advice; if you are redistributing the guide inside a commercial product, read the LICENSE file yourself.

Editorial conclusion

Adopt it if your team is starting an Angular 1 or Angular 2 project and wants naming and folder conventions written down before the first pull request. Do not adopt it as a modern Angular reference: the repository carries a1/ and a2/ guides, and the README does not document an Angular 3 or later edition. Before you copy anything, open the version directory that matches your framework, check the last push date against your own Angular version, and decide through an issue whether your team's disagreement is worth a pull request.

Frequently asked questions

What is the purpose of johnpapa/angular-styleguide?

The README describes it as an opinionated style guide for syntax, conventions and structuring Angular applications, showing the conventions the author uses and why he chooses them. It is intended as a starting point for development teams that want consistency.

Which version of johnpapa/angular-styleguide should I read?

The README says there are multiple versions of Angular and therefore multiple versions of the guide, and that you should choose your guide appropriately. It points Angular 1 readers to a1/README.md and Angular 2 readers to a2/README.md.

Does johnpapa/angular-styleguide install as a package?

No. The repository contains Markdown guides in a1/ and a2/ plus a LICENSE and README, and the README documents no npm package, CLI or configuration file. You use it by cloning the repository and reading the directory that matches your Angular version.

How do I contribute a change to johnpapa/angular-styleguide?

The README asks you to discuss the change in a GitHub issue first, then open a pull request that references the issue and explains the change and why it adds value. The pull request is evaluated and either merged or declined.

What licence does johnpapa/angular-styleguide use?

The repository is MIT licensed, with a copyright line reading "Copyright (c) 2014-2016 John Papa". The README summarises it as "tldr; Use this guide. Attributions are appreciated."

Official sources

  1. Issues
  2. johnpapa/angular-styleguide on GitHub
  3. License: MIT
  4. Project website
  5. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/johnpapa-angular-styleguide.svg)](https://hysenlabs.com/projects/johnpapa-angular-styleguide)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/johnpapa-angular-styleguide.svg)](https://hysenlabs.com/projects/johnpapa-angular-styleguide)

Was this useful?