让开源，少一点语言距离。
npm包中文文档

@aurelienbbn/agentlint-plugin-shopify-app

中文文档
0.1.5发布于 2026/10/14MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 2608

Custom agentlint rules for Shopify app and extension code.

原始使用文档
中文原文
文档目录9 节
  1. Quick start
  2. Rules
  3. What fires
  4. Checkout: first paint waits on nothing avoidable
  5. app-ux-review 🧪: you map files to review areas
  6. Migration
  7. Sources
  8. Registered contract inventory
  9. Credited concepts

@aurelienbbn/agentlint-plugin-shopify-app

npm downloads CI license node

15 agentlint reviews for Shopify apps and extensions: a deterministic trigger finds the spot, a reviewer checks it against Shopify's own guidance.

[!WARNING] Requires the engine @aurelienbbn/agentlint >=0.3.0 <0.9.0 as a peer. Evidence.

A finding is something to inspect, not a policy violation. Resolutions in .agentlint/acceptances.jsonl keep review evidence; neither they nor a clean run prove App Store or Built for Shopify eligibility.

Quick start

agentlint init --preset "@aurelienbbn/agentlint-plugin-shopify-app#starterPreset"
agentlint rules test
agentlint rules scan --review
agentlint next --format json

init keeps an existing config and prints the install command; never installs. Calibrate bindings before requiring agentlint check --all.

import { defineConfig } from "@aurelienbbn/agentlint";
import { checkoutExtensionPreset, shopifyAppPreset } from "@aurelienbbn/agentlint-plugin-shopify-app";

export default defineConfig({ extends: [shopifyAppPreset, checkoutExtensionPreset] });

Rules

RuleshopifyAppappServercheckoutExtensionstarterRevOptions
session-token-auth✅✅2 ⚠️identityKeyPattern
form-error-recovery✅✅1errorAttribute
action-label-clarity✅1ambiguousLabelPatterns
banner-usage✅1
destructive-action-review✅1toneAttribute, destructiveTone
modal-workflow-review✅1
no-pressure-copy✅1languages (en, fr, de), additionalPatterns
review-solicitation✅1additionalPatterns, useDefaultPatterns
settings-save-bar✅1 ⚠️formElementPattern, saveBarMarkerPattern
admin-api-loop-review✅1graphqlCalleePattern
webhook-handler-review✅1topicPattern
checkout-network-discipline✅2 ⚠️networkCallPattern
scope-change-review 🧪1manifestPattern
flow-action-handler-review 🧪1handlerPathPattern
app-ux-review 🧪1targets, elementNamePattern

Presets are <name>Preset. 🧪 in no preset: register scopeChangeReview, flowActionHandlerReview / a configured defineAppUxReview(...). All rules: agent authority, detector 1. Presets ignore **/*.d.ts. ⚠️ see migration.

PresetScopeNarrow it to
shopifyAppPreset**/*.{ts,tsx,js,jsx} + **/locales/**/*.jsonyour App Home source, when the repo holds several Shopify surfaces
appServerPreset**/*.{ts,tsx,js,jsx}, tests excludedserver code (app/routes/**, app/**/*.server.*, workers) beside other GraphQL clients
checkoutExtensionPresetextensions/**/*.{ts,tsx,js,jsx}

Every rule exports a defineX(options) factory; register the configured instance under the same rule id. Stateful regular expressions are reset before each match.

defineNoPressureCopy({ languages: ["en", "fr"], additionalPatterns: [/última oportunidad/iu] });
defineSettingsSaveBar({ saveBarMarkerPattern: /useSaveBar/ });

What fires

<form data-save-bar>…</form>           // ✅ direct literal attribute
<form title="SaveBar">…</form>          // ❌ a mention isn't a marker
<form data-save-bar={false}>…</form>    // ❌ false or dynamic values don't count

for (const id of ids) await admin.graphql(QUERY, { variables: { id } }); // ❌ admin-api-loop-review
for (const edge of (await admin.graphql(QUERY)).edges) {
  total += edge.node.count;
} // ✅ the iterable

A save bar elsewhere in the source no longer suppresses a form's review. App Home rules match exact JSX names: no import, wrapper or spread resolution; set elementNamePattern for your reviewed wrappers.

Copy, auth and forms: triggers and boundaries
RuleFires onBoundary
no-pressure-copyurgency, scarcity or outcome-guarantee wording in JSX text or stringsdefault lexicons: en, fr, de
session-token-authdocument.cookie; localStorage / sessionStorage getItem / setItem with an identity-carrying keyidentityKeyPattern default: token/session/auth/jwt/credential/api-key. Lexical candidates, not authentication verification
settings-save-bara <form> / <Form> opening element without its own save-bar markera custom saveBarMarkerPattern stays a trusted escape hatch over the opening element
review-solicitationspecific review-request phrases in JSX text or stringsEnglish, French and German defaults are partial lexicons; neutral requests still need placement and incentive review

Recognized save-bar markers don't prove dirty-state or navigation behavior: exercise those states with a route review.

session-token-auth also asks that offline tokens are read through the library's session storage: copies kept elsewhere go stale under the expiringOfflineAccessTokens future flag. Guidance uses current ID token terminology; the rule ID stays session-token-auth.

English style and readability scores are never treated as universal locale or accessibility requirements.

App Home components: triggers and boundaries

They don't resolve imports, wrappers, dynamic components, spread props or generated templates. A name matching another Shopify surface doesn't make App Home guidance apply there: scope these rules to the right files.

RuleFires onBoundary
action-label-clarityconfigured ambiguous literal text directly inside s-button or s-linkambiguousLabelPatterns replaces a small English default lexicon; translation helpers and arbitrary strings aren't analyzed
banner-usages-banner, including dismissibleneeds rendered context and dismissal-persistence evidence; a correct prop can't establish either
destructive-action-reviews-button or s-clickable with literal tone="critical"dynamic tones need separate review
form-error-recoverya known Polaris input control with a possibly active error propempty, false, null, undefined literals stay silent; runtime expressions schedule review
modal-workflow-reviews-modal or s-app-windowreviews entry paths, task fit, dismissal, recovery; structural slot rules are separate

The Text field reference encourages feedback during typing; the Alerts guide recommends errors after blur. form-error-recovery exposes that difference and asks for untouched, typing, blur, submission and recovery evidence. It doesn't ban onInput or certify validation timing from a prop.

Server: loops, webhooks, Flow actions, scopes
RuleFires onStays silent
admin-api-loop-reviewadmin.graphql, client.request or client.query (optionally qualified) inside a for / for…of / while / do body, or a .map / .forEach / .flatMap callbacka for…of iterable, a for initializer, functions merely defined inside a loop; test files
webhook-handler-reviewonce per file: authenticate.webhook, an X-Shopify-Hmac-Sha256 / X-Shopify-Topic / X-Shopify-Webhook-Id string, or a known topic literal (orders/create, APP_UNINSTALLED) as a switch case or comparison operandtest files
flow-action-handler-review 🧪once per file: authenticate.flow, an action_run_id / action_definition_id key (member, destructuring, computed or object key), or a path matching handlerPathPatternpreview and validation endpoints (no run id), the key as plain text; test files
scope-change-review 🧪change rule: shopify.app.toml / shopify.app.<name>.toml whose [access_scopes] scopes / optional_scopes (or legacy top-level scopes) gained entries since the Git baselineremoved, reordered or demoted scopes; unchanged manifests are never inventoried, even with --all
Limit
admin-api-loop-reviewgraphqlCalleePattern adds project wrappers; imports and aliases aren't resolved. Bounded pagination is legitimate: the finding asks for the bound and the throttle handling
webhook-handler-reviewtopicPattern replaces the default topic lexicon. Constant-time database work inline passes; dedup or queueing in another file is evidence the reviewer cites, not something the trigger resolves
flow-action-handler-reviewasks for HMAC, action_run_id dedup, a status within 10 s (202 for longer work), 4xx only for permanent failures, and a return_value body. Doesn't read runtime_url from TOML: set handlerPathPattern for handlers that delegate the payload elsewhere. A manual HMAC check also triggers webhook-handler-review
scope-change-reviewreads two known keys; not a TOML parser. Scope necessity is judged, never proven

Checkout: first paint waits on nothing avoidable

checkout-network-discipline fires on fetch (bare or window. / globalThis. / self.-qualified) and shopify.query() under extensions/**; networkCallPattern adds a project fetch wrapper. The trigger can't establish latency: review measured request and rendering timings against both performance sources. Keep network calls out of module scope.

What the checkout sources say
SourceSays
Checkout extension performanceload necessary initial data in the extension callback before first paint, so Shopify's loading skeleton stays until stable content is ready
Checkout best practicesresponse time below one second; initial skeletons
Checkout capabilitiesbackend trusts only verified session-token claims · no buyer-callable sensitive endpoint · answers with Access-Control-Allow-Origin: * · doesn't expect logged_in_customer_id on App Proxy calls from an extension

app-ux-review 🧪: you map files to review areas

Dormant by default; purpose is never inferred from filenames. Prefer narrowly configured rules over stretching the App Home preset across checkout, admin and Sidekick extensions.

areas  home · onboarding · navigation · responsive · premium · visual-editor · inputs
       collections · content · copy-mechanics · checkout · admin-extension · sidekick
Configuration and reporting 
import { defineConfig } from "@aurelienbbn/agentlint";
import { defineAppUxReview, shopifyAppPreset } from "@aurelienbbn/agentlint-plugin-shopify-app";

export default defineConfig({
  extends: [shopifyAppPreset],
  rules: [
    defineAppUxReview({
      targets: [
        { filenamePattern: /\/app\._index\.tsx$/, areas: ["home", "responsive"] },
        { filenamePattern: /editor\.tsx$/, areas: ["visual-editor"] },
        { filenamePattern: /extensions\/admin\//, areas: ["admin-extension"], trigger: "file" },
        { filenamePattern: /sidekick\.ts$/, areas: ["sidekick"], trigger: "file" },
      ],
    }),
  ],
});
Target kindReports at
page (default)the first matching s-page
trigger: "file"the TS/JS program node: extension entry points without page JSX

Each trigger reports once per file, combining matching areas; the finding names only those areas. Review them, attach the source revision and browser or runtime observations, and record unresolved states. The rule doesn't read manifests or discover extension targets.

Migration

RuleChange
⚠️ checkout-network-discipline, session-token-auth rev 2added the capabilities security checks and the offline-token session-storage check
⚠️ settings-save-baronly a direct literal data-save-bar on the form suppresses review

Requirement IDs and evidence boundaries: policy/shopify-requirements.json and the repository Shopify checks.

Agentlint rule contract
FactDetail
rule shapelifecycle, standard (revision), detector (version), binding (id, authority, scope, material options)
composingdefineConfig({ extends: [preset] }) or defineConfig({ rules: [configuredRule] }); repeated uses need distinct binding ids
authoritydefaults permit agent acceptance; repository owners choose scope and can raise authority to human
accepting a findingrequires matching current evidence and authority
fixtures@aurelienbbn/agentlint/testing runs the embedded activation/silence fixtures with the real parser

Sources

Independently implemented from Shopify's official documentation; no Shopify code or templates vendored. Greppable @attribution tags mark source concepts in implementation files. starterPreset onboarding: conceptual inspiration from desloppify by Peter O'Malley; no code or guidance copied.

Inspected pages, by date and rule
InspectedSourceFeeds
2026-09-05Built for Shopify requirements, App Store requirementsapplicability and numbered obligations
2026-09-05Content, Marketing, Alerts, Formsreadable actions, restrained promotion, understandable feedback, organized editing
2026-09-05Voice and tone, Grammar and mechanicssituation-appropriate copy, locale-specific mechanics
2026-09-05App structurerendered review of admin extension size and workflow fit
2026-09-05App Home, Onboarding, Navigation, Layoutroute-level review areas
2026-09-05Polaris Button, Banner, Modal, Text fieldcomponent intent and behavior
2026-09-05Polaris Switch, Color picker, Table, Choice list, Menu, Tooltip, Paragraphtargeted input, collection and content review
2026-09-05Checkout extension performance, Checkout best practicesinitial rendering sequence, measured response-time target
2026-09-05ID tokens, Save Bar APIcurrent platform guidance
2026-09-19Admin GraphQL API, API limits, bulk operations, idempotencyadmin-api-loop-review
2026-09-19HTTPS webhook delivery, duplicate webhooks, webhook best practices, authenticate.webhookwebhook-handler-review
2026-09-19access scope management, protected customer datascope-change-review
2026-09-19checkout capabilities, shopify-app-js future flagsextended checkout and authentication guidance
2026-09-24Flow action endpoints, create a Flow action, complex data typesflow-action-handler-review

Registered contract inventory

Generated from package exports by pnpm catalog. Rule-specific options and limitations are described above and in the source tests.

Rule/checkTrigger or review scope
action-label-clarityReviews configured ambiguous literal labels on Polaris actions in their merchant context.
admin-api-loop-reviewFlags Admin GraphQL calls issued from loops or iteration callbacks for cost, batching, and throttle review.
app-ux-reviewRequests UX evidence for explicitly configured app routes and extension entry points.
banner-usageReviews App Home banners for purpose, context, dismissal persistence, and competing messages.
checkout-network-disciplineFlags network calls in checkout extension code for latency-budget review.
destructive-action-reviewReviews actions explicitly marked with a destructive tone for consequences, confirmation, and failure handling.
flow-action-handler-reviewFlags Shopify Flow action runtime handlers once per file for signature, duplicate-run, response-time, status-code, and return-value review.
form-error-recoveryReviews Polaris form controls with error wiring for understandable, persistent recovery feedback.
modal-workflow-reviewReviews modal and app-window workflows for merchant initiation, task fit, and usable dismissal.
no-pressure-copyFlags urgency, scarcity, or outcome-guarantee copy in merchant-facing UI.
review-solicitationReviews app-rating request phrases for neutral wording, incentives, placement, and merchant control.
scope-change-reviewFlags access scopes added to a Shopify app manifest since the baseline for necessity review.
session-token-authFlags cookie or Web Storage identity state in embedded Shopify app code.
settings-save-barFlags forms in embedded app pages that lack a contextual save bar integration.
webhook-handler-reviewFlags Shopify webhook handlers once per file for response-time, duplicate-delivery, ordering, uninstall, and compliance review.

Credited concepts

版本与发布记录

@aurelienbbn/agentlint-plugin-shopify-app 共发布 6 个版本，首次发布于 2026/09/25；过去 12 个月发布了 6 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.5latest2026/10/1424 天前
0.1.42026/10/1325 天前
0.1.32026/09/301 个月前
0.1.22026/09/301 个月前
0.1.12026/09/251 个月前
0.1.02026/09/251 个月前

关于 @aurelienbbn/agentlint-plugin-shopify-app 的常见问题

@aurelienbbn/agentlint-plugin-shopify-app 是什么？

Custom agentlint rules for Shopify app and extension code.

如何安装 @aurelienbbn/agentlint-plugin-shopify-app？

在项目目录运行 npm install @aurelienbbn/agentlint-plugin-shopify-app，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aurelienbbn/agentlint（>=0.3.0 <0.9.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@aurelienbbn/agentlint-plugin-shopify-app 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@aurelienbbn/agentlint-plugin-shopify-app 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@aurelienbbn/agentlint-plugin-shopify-app 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js ^22.19.0 || ^24.11.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@aurelienbbn/agentlint-plugin-shopify-app 可以商用吗？

@aurelienbbn/agentlint-plugin-shopify-app 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@aurelienbbn/agentlint-plugin-shopify-app 的下载量有多少？

根据 npm 官方下载统计，@aurelienbbn/agentlint-plugin-shopify-app 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,608 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@aurelienbbn/agentlint-plugin-shopify-app 还在维护吗？

最新版本 0.1.5 发布于 2026/10/14（24 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/09/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。