Choosing the Right Axe DevTools Linter Setup

Axe DevTools Linter can be used in many ways, and the right combination depends on how your team writes, reviews, and ships code. This guide walks through the main decisions so you can choose a setup that fits your circumstances. Most teams combine several of these options rather than picking just one.

The decisions fall into four areas:

1. Where analysis runs (whether files are linted locally or on a server, and which deployment model hosts that server)
2. Where linting happens in your workflow (IDE, pre-commit hook, CI/CD)
3. Whether you need to configure component libraries
4. When to add other integrations such as SonarQube

1. Choose Where Analysis Runs

There are two related choices here: whether your files are analyzed on your own machine or sent to a server, and, if a server is involved, which kind of server hosts it.

Local or Server-Based Linting

Where your files are analyzed, and whether their contents leave your machine, depends on the integration. The three integration families behave differently:

• IDE integrations always lint locally. The VS Code extension and the JetBrains plugin analyze files on your own machine with a bundled component, so file contents never leave your computer. They require no API key or license key to lint.
• The Connector can lint either way. By default the Connector sends files to an Axe DevTools Linter server, but its --local option analyzes them on your machine instead, so their contents never leave it. Deque recommends local linting for most cases: it is significantly faster and less prone to network problems, especially when linting large numbers of files. Whichever way you lint, the Connector authenticates, as described in Connector authentication below.
• The GitHub Action is always server-based. The GitHub Action sends changed files to an Axe DevTools Linter server for analysis. It has no local-linting mode, so this option always sends file contents to the server.

Connector Authentication

When you use the Connector, you authenticate with one of two credentials, whether you lint locally or against a server:

• API key (the --api-key option): You manage API keys yourself as part of your Axe Account. The Connector contacts a remote server to validate the key and report usage (the lines of code linted). This happens even when you lint locally.
• License key (the --license-key option): You request a license key from Deque's Help Desk. It authenticates with no network activity and does not track usage, which makes it the right choice for air-gapped networks or environments with strict outbound rules. It is available only with local linting.

This gives the Connector three ways to run:

The IDE integrations need no credential to lint. The GitHub Action authenticates with an API key; its setup guide covers the workflow for both SaaS and on-premises servers.

Server Deployment Model

If you lint against a server, or authenticate with an API key while linting locally, you also choose which kind of server hosts Axe DevTools Linter. This affects setup effort, whether your files leave your network, and how you authenticate.

Choose SaaS for the fastest start and no infrastructure to maintain. Choose on-premises when policy requires that source code stay within your network, or when you want full control over the server. Choose private cloud when you want a dedicated Deque-managed instance without running the server yourself.

2. Choose Where Linting Happens in Your Workflow

Accessibility feedback is most useful early and often. The integrations below apply at different points in the development lifecycle, and they work well together: catch issues as you type, again before a commit, and once more in the pull request.

A common, layered approach is:

1. IDE extension so developers see issues immediately as they write code.
2. Pre-commit hook or GitHub Action as a gate so issues are caught before or during code review.
3. Connector in CI/CD to enforce checks across the whole codebase and to feed other systems.

You do not have to adopt all three layers at once. Teams often start with the IDE extension, then add a pull request check once they are ready to enforce standards across the team.

3. Decide Whether to Configure Component Libraries

By default, Axe DevTools Linter checks standard HTML elements and framework markup. If your code uses custom components (for example, a <custom-image> that renders an <img>), the linter cannot check them for accessibility until you tell it how each component maps to a standard element.

You should configure component linting if:

• Your codebase relies on a design system or custom component library, and
• You want accessibility issues inside those components to be flagged.

There are two paths:

• Preconfigured component libraries: If you use Cauldron React, Material UI (@mui/material), or React Native, support is built in. See Preconfigured Component Libraries.
• Custom mappings: For your own components, create mappings in your configuration. See Linting Custom Components for an overview, then the walkthrough for VS Code and JetBrains or the REST endpoint.

Configuration options are shared across the IDE integrations, the Connector, and the REST API, and are documented in Configuring Axe DevTools Linter.

4. Decide When to Add Other Integrations

The integrations in step 2 cover most teams' needs. Consider the following additional integrations when they match tools you already use:

These integrations are all built on the Connector, which produces the linting results that each system consumes. The general rule: reach for another integration when it lets accessibility findings surface in a tool your team already relies on, rather than adding a new tool for its own sake.

Putting It Together

A typical setup for a team using SaaS might be:

• The VS Code extension (or JetBrains plugin) for every developer, for feedback while coding.
• The GitHub Action on pull requests, so accessibility issues are visible during code review.
• Custom component mappings if the team uses a design system.
• SonarQube integration only if the team already centralizes code quality there.

A team with stricter data-handling requirements might replace SaaS with the on-premises deployment and use the Connector with --local in their CI/CD pipeline so source code never leaves their network.

If you are unsure which combination fits your circumstances, contact Deque's help desk.