Theme
Version
GitHub PyPI Discord
On this page

Template linting

Some template mistakes show up only when the page renders, and some never raise an error at all:

  • A misspelled variable fails only when the page renders.
  • A Vue binding can read a Python loop variable the browser never sees.
  • The browser silently ignores a misspelled attribute such as titel, or a value it does not accept.
  • A misspelled c-if renders the element anyway.
  • A broken Vue expression, or a <div> inside a <p>, stops a component that uses Vue from rendering.

Citry's lint rules find these mistakes in the editor and in citry check, before anyone opens the page.

Your application owns the rules. You set them once on your Citry instance, and both citry check and the editor read them. There is no separate editor setting.

RuleWhat it catchesDefault
citry.template.unknown-variableA template variable that comes from nowhereerror
citry.vue.unknown-variableA name in a Vue expression that the component does not send to the browsererror
citry.component-js.unknown-variableAn undeclared name in $component codeerror
citry.component-js.unknown-memberA misspelled this.<name> or component.<name>error
citry.vue.python-variableA Vue expression that reads a Python loop variablewarning
citry.template.alpine-attributeA leftover Alpine x-* attributewarning
citry.template.alpine-cloakA leftover x-cloak, which hides the element for gooderror
citry.template.invalid-attribute-valueAn HTML attribute value the browser does not accept, or any value on a boolean attribute, such as disabled="false"error
citry.template.misspelled-directiveA typo in a directive, such as c-iff or v-ifferror
citry.template.misspelled-attributeA typo in an attribute name, such as titelerror
citry.template.misspelled-elementA typo in a tag name, such as <dvi>error
citry.template.unknown-aria-attributeAn aria-* name that ARIA does not defineerror
citry.vue.misspelled-eventA typo in a DOM event name, such as @clikwarning
citry.vue.invalid-expressionA Vue expression that is not valid JavaScripterror
citry.vue.compile-errorAnything else Vue's compiler rejects, such as a <div> directly inside a <table>error
citry.browser.invalid-model-targetv-model on an element that holds no valueerror
citry.browser.undeclared-component-eventA listener for an event the child component does not declarewarning
citry.template.invalid-nestingA block such as <div> inside a <p>error
citry.template.duplicate-idTwo elements with the same iderror
citry.template.missing-image-altAn <img> without alt textwarning
citry.template.csp-incompatibleA <script>, <style>, on* attribute, or javascript: URL that a strict Content Security Policy blocksoff; follows security_csp
citry.browser.missing-component-keyA component that <c-for> repeats without #c-key, on a page that uses Vueerror
citry.browser.prop-assignmentA component that assigns to one of its own propserror
citry.browser.unknown-server-event-fieldA key in @c-* arguments that the handler does not accepterror
citry.browser.missing-server-event-field@c-* arguments without a field the handler requireserror
citry.browser.incompatible-server-event-fieldA literal in @c-* arguments of a type the handler rejectserror
citry.browser.unknown-form-fieldA control in a submitted form whose name the handler does not accepterror
citry.browser.missing-form-fieldA submitted form without a control for a field the handler requireserror
citry.css.misspelled-variableA var(--name) that misspells a css_data() keywarning
citry.css.misspelled-classA class one typo away from a class in the component's CSS, such as bord for .boardwarning
citry.css.undeclared-classA class that no CSS read by Citry declaresoff
citry.css.undeclared-variableA var(--name) that nothing setsoff
citry.template.unknown-urlA link to a path your app has no page or file forwarning
citry.template.unknown-inject-keyA self.inject("key") whose key no component above provideswarning

Fix unknown names

A template variable must come from the component's template data, a c-for or c-fill binding around it, or a global you configured. Anything else is an error:

{# error: Template variable 'usr' is not available
   in this template. #}
<p>{{ usr.name }}</p>

Vue expressions follow the same idea. A name in :title, v-text, or @click must be something the component sends to the browser, such as a js_data() key, or a Vue or Citry helper:

{# error: Vue variable 'submitting1' is not available
   in this component. #}
<button :disabled="submitting1">Save</button>

Inside $component(...), every name must be declared in that code, destructured from the callback's argument, or be a browser global:

$component({
  onServerRender({ component }) {
    // error: Component JavaScript variable 'settings' is not defined.
    component.ready = settings.ready;
  },
});

Usually the fix is to correct the spelling, or to read the value from the component, such as component.ready. If another script on the page really provides the name, declare it.

A misspelled member of the component is an error too. Citry reports a component.<name> or this.<name> read that names no js_data() key, prop, data() key, setup binding, method, computed value, or injection:

// js_data() returns {"likes": ...}
$component(({ component }) => {
  // error: Component instance member 'like' is not defined
  // by this component.
  console.log(component.like);
});

Citry runs this check only when it can see every js_data() key and every Vue Options section in the source. It skips names that start with $ or _, so a Vue plugin that adds a property to every component should name it with a $ prefix, such as $api. An unprefixed plugin property, such as this.axios, is reported.

Python loops in Vue

Python runs a c-for loop on the server. Vue evaluates :title later, in the browser, where item does not exist:

<!-- Wrong: Vue looks up `item` in browser state. -->
<li c-for="item in items" :title="item"></li>

<!-- Right: Python sets the attribute for each item. -->
<li c-for="item in items" c-title="item"></li>

Citry reports this once per read. When it knows every name the component sends to the browser, it reports a citry.vue.unknown-variable error whose message says the name is a Python variable. Otherwise, or when you set rule_unknown_vue_variable to "ignore", it reports a citry.vue.python-variable warning that suggests the c- attribute.

The warning also fires when the component's browser data has a name equal to the loop variable. Vue then shows the browser value instead of the loop value, with no error, so the message suggests the c- attribute or renaming one of them.

The same applies to c-fill bindings and to every Vue expression, including v-text, v-show, and @click. A Vue v-for or slot alias with the same name around the expression is fine, because Vue then reads its own value.

Declare outside names

Some names reach a template or browser code from somewhere Citry cannot see, such as a framework integration or a script on the host page. Declare them on the application so Citry stops reporting them.

Keys in template_globals are known automatically, with types guessed from their values. For other names, pass a LintSettings:

from collections.abc import Callable
from typing import Annotated

from citry import Citry, LintSettings

app = Citry(
    template_globals={"site_name": "Citry"},
    lint=LintSettings(
        template_variables={
            "request": Annotated[
                "django.http.HttpRequest",
                "The current framework request.",
            ],
            "url_for": Callable[[str], str],
        },
        vue_variables={
            "$analytics": Annotated[
                "myapp.browser.Analytics",
                "Analytics added as a custom Vue property.",
            ],
        },
        component_js_globals={
            "featureFlags": Annotated[
                "myapp.browser.FeatureFlags",
                "Flags set by the host page.",
            ],
        },
    ),
)
  • template_variables are names that reach the template from another integration, such as a request object.
  • vue_variables are custom Vue properties, or values that a Vue scope outside Citry provides.
  • component_js_globals are real globals that a project script defines, available inside $component.

These declarations only tell the checker about the names. They do not provide a value at runtime. Each value is a type annotation, which the editor shows on hover. Annotated[T, "description"] adds a description too. The editor resolves type names written as strings, such as "django.http.HttpRequest", in your project's environment.

Do not declare a value that onServerRender receives, such as props, refs, or event helpers. Read it from the callback's argument or the component instance instead. Declaring it as a global would hide the bug where you forgot to destructure it.

List template data keys

When template_data() returns a dict literal, Citry reads its keys and checks the template against them. When the method builds its result in a way Citry cannot read, such as by calling a helper function, Citry cannot see the keys. It then reports every name in the template, even names the helper does return:

{# error: Template variable 'img_attrs' is not declared.
   Citry could not determine whether it is supplied
   dynamically. #}
<img
  c-src="src"
  c-alt="alt"
  c-attrs="img_attrs"
>

List every key the method returns in the component's Lint class:

from citry import Component

class Avatar(Component):
    class Lint:
        template_data_keys = ("src", "alt", "img_attrs")

    def template_data(self, kwargs, slots):
        # Returns {"src": ..., "alt": ..., "img_attrs": ...}.
        return build_avatar_data(kwargs)

    template = """
      <img
        c-src="src"
        c-alt="alt"
        c-attrs="img_attrs"
      >
    """

Citry then accepts the listed names and reports any other name, such as a typo like img_attr. Only citry check and the editor read the list; rendering ignores it. A subclass's list replaces its base class's list, template_data_keys = None clears it, and a TemplateData schema on a subclass replaces it too.

If the method also writes a key as a literal, such as {"title": ...} or data["title"] = ..., and the list leaves it out, citry check warns. This warning has no rule_* setting. Citry cannot see the keys the helper adds, so keep the list in step with the helper yourself: a listed key that the helper never returns passes the check, and the page fails with KeyError when it renders.

Citry checks the list when the class is defined:

  • A value that is not a tuple, list, or frozenset of strings raises TypeError. A set raises it too.
  • A name that cannot be a Python variable name, such as "class" or "my-key", or a name listed twice, raises ValueError.
  • A component that declares both the list and a TemplateData schema raises TypeError, because the schema already names every key.

Change rule severity

Most rules have a rule_* setting on LintSettings that accepts "ignore", "warning", or "error". Warnings are shown but do not fail citry check; errors do, and "ignore" turns the rule off. The strict CSP rule follows security_csp instead. Some rules have no setting; the Diagnostics page marks each rule you can change. These are the defaults:

from citry import Citry, LintSettings

app = Citry(
    lint=LintSettings(
        rule_unknown_template_variable="error",
        rule_unknown_vue_variable="error",
        rule_unknown_component_js_variable="error",
        rule_unknown_component_js_member="error",
        rule_vue_python_variable="warning",
        rule_alpine_attribute="warning",
        rule_alpine_cloak="error",
        rule_invalid_attribute_value="error",
        rule_misspelled_directive="error",
        rule_misspelled_attribute="error",
        rule_misspelled_element="error",
        rule_unknown_aria_attribute="error",
        rule_misspelled_event="warning",
        rule_invalid_vue_expression="error",
        rule_vue_compile_error="error",
        rule_invalid_model_target="error",
        rule_undeclared_component_event="warning",
        rule_invalid_nesting="error",
        rule_duplicate_id="error",
        rule_missing_image_alt="warning",
        rule_missing_component_key="error",
        rule_prop_assignment="error",
        rule_unknown_server_event_field="error",
        rule_missing_server_event_field="error",
        rule_incompatible_server_event_field="error",
        rule_misspelled_css_variable="warning",
        rule_misspelled_css_class="warning",
        rule_undeclared_css_class="ignore",
        rule_undeclared_css_variable="ignore",
        rule_unknown_url="warning",
        rule_unknown_inject_key="warning",
    ),
)

LintSettings also has two translation rules: rule_i18n_missing_param_type (Change type warnings) and rule_i18n_cross_language_fallback (Change fallback warnings).

LintSettings and a component's nested Lint class also accept check_input_types, which is not a lint rule. It controls the check that raises TypeError when a component renders with an input of the wrong type, and citry check and the editor ignore it (Turn the check off). LintSettings.include_libraries is not a lint rule either: it makes citry check report findings in the components of a library you registered (Library components).

Override one component

When one component works differently, give it a nested Lint class with the settings to change:

from typing import Annotated

from citry import Component

class AccountCard(Component):
    class Lint:
        rule_unknown_template_variable = "warning"
        rule_unknown_component_js_member = "warning"
        template_variables = {
            "account_context": Annotated[
                "myapp.accounts.AccountContext",
                "Added by the account page integration.",
            ],
        }
        component_js_globals = {
            "accountClient": Annotated[
                "myapp.browser.AccountClient",
                "Client set up by the account page.",
            ],
        }

Subclasses inherit Lint. The nearest setting wins, and declared names merge by name. Set Lint = None on a subclass to drop the inherited overrides and use the application's settings again.

Alpine leftovers

Citry uses Vue, so an Alpine attribute left over from older templates does nothing. Citry renders x-data or x-on:click unchanged, and nothing in the browser reads it. Each x-* attribute on an HTML element is a citry.template.alpine-attribute warning:

{# Warning: nothing reads x-data or x-on:click #}
<div x-data="{ open: false }">
  <button x-on:click="open = !open">Menu</button>
</div>

Move the state into the component's js_data() or $component, and write the listener as a Vue @click. See Vue in templates.

A leftover x-cloak does real harm. Nothing removes the attribute, so a CSS rule such as [x-cloak] { display: none } hides the element for good. Citry reports it as a citry.template.alpine-cloak error. Delete both the attribute and the CSS rule; the HTML from the server already shows the content.

Only Alpine's own directive names are reported, such as x-data, x-on:click, or x-intersect, and only on HTML elements and <c-element>. Other x-* names, such as x-webkit-airplay, are ordinary HTML. On a component tag, an x-* attribute is a Python keyword argument.

When another library on the page reads x-* attributes, turn the warning off for the components that use it:

from citry import Component

class DatePicker(Component):
    class Lint:
        rule_alpine_attribute = "ignore"

Or for the whole application, with LintSettings(rule_alpine_attribute="ignore").

Invalid attribute values

Some HTML attributes accept only a few keywords. draggable takes "true" or "false", and <input type> takes a type the browser knows. The browser ignores any other value or falls back to a default, so the attribute silently does nothing. Citry reports such a value as a citry.template.invalid-attribute-value error and suggests the closest valid keyword:

{# Error: 'treu' is not a valid value; did you mean 'true'? #}
<div draggable="treu">Drag me</div>

{# Error: did you mean 'datetime-local'? #}
<input type="datetime" name="start">

A boolean attribute, such as disabled, required, or checked, is on whenever it is present, whatever its value. So disabled="false" still disables the button. Citry reports any value other than an empty one or the attribute's own name:

{# Wrong: the button is disabled, because 'false' still
   turns the attribute on #}
<button disabled="false">Search</button>

{# Right: leave the attribute out to turn it off #}
<button>Search</button>

{# Right: let Vue add or remove it #}
<button :disabled="searching">Search</button>

disabled="true" is reported too, because the value does nothing: write disabled on its own. A bound JavaScript boolean, such as :disabled="false", is fine, but the string :disabled="'false'" is reported, and the message suggests binding the boolean instead. draggable, spellcheck, and contenteditable take "true" and "false" as keywords, so they are not boolean attributes.

The keywords come from the HTML Standard. The check covers:

  • attributes every element accepts, such as dir, hidden, contenteditable, draggable, spellcheck, translate, inputmode, enterkeyhint, autocapitalize, and popover;
  • type on <input>, <button>, <ol>, <li>, and <ul>;
  • method, enctype, and autocomplete on <form>;
  • loading, decoding, fetchpriority, crossorigin, and referrerpolicy on the elements that take them, such as <img>;
  • preload on <audio> and <video>, kind on <track>, wrap on <textarea>, and scope on <th>;
  • target and formtarget, http-equiv on <meta>, and name on <iframe> and <object>, as described below.
  • boolean attributes, such as disabled, required, and checked, on the elements that take them.

Letter case does not matter, so type="Email" passes. An attribute that accepts an empty value, such as hidden, may also be written with no value.

A Vue binding whose value is one JavaScript string is checked too, because it sets the same text:

{# Error: 'rlt' is not a valid value; did you mean 'rtl'? #}
<div :dir="'rlt'">...</div>

When a script on the page reads its own values from one of these attributes, turn the rule off for the components that use it:

from citry import Component

class LegacyWidget(Component):
    class Lint:
        rule_invalid_attribute_value = "ignore"

Misspelled directives

Citry reads only its own directive names, such as c-if and c-for. Any other c- name on an HTML element sets an ordinary attribute from the Python value, so a typo does not fail. The element below always shows up, whatever show is:

{# Error: 'c-iff' is not a Citry directive, so it renders an
   HTML attribute named 'iff'. Did you mean 'c-if'? #}
<div c-iff="show">Details</div>

{# Right: the element renders only when show is true #}
<div c-if="show">Details</div>

Citry reports a c- name as a citry.template.misspelled-directive error when the part after c- is not an attribute of that element and it looks like a directive:

  • if, elif, else, for, empty, or bind with two neighboring letters swapped, one letter typed twice, or one letter left out, such as c-fro, c-iff, or c-ele;
  • a directive in other letter case, such as c-If;
  • a spelled-out c-elif, such as c-else-if or c-elseif;
  • c-show, which you write as c-if, or a Vue directive written with c-, such as c-model, which you write as v-model;
  • c-key or c-ignore, which you write as #c-key or #c-ignore.

A different letter, or an extra letter that is not a double, does not count as a typo, because it usually makes an ordinary word: c-kind is not read as c-bind, and c-form or c-fork not as c-for. A name one letter short of a directive is not reported when it is itself a word or a single letter, such as c-or, c-bid, c-bin, or c-f.

An attribute the element really has is never reported, in any letter case: c-id, c-ID, c-form on <input>, and every c-data-* and c-aria-* name pass. <c-element> accepts the attributes of every element. A custom element such as <my-button> can define its own attributes, so there c-show, c-model, c-key, and c-ignore pass; typos such as c-iff or c-If are still reported. Component tags and elements inside <svg> or <math> are skipped; on a component tag, a c- name is a Python keyword argument.

An attribute named like a directive, such as for on <label>, cannot take c-, because c-for is always the loop. Pass it through c-bind.

When the attribute really is meant for the browser, such as a show attribute that a page script reads (c-show on a <div> is reported, with c-if as the suggestion), pass it through c-bind, which this rule does not read:

<div c-bind="{'show': expanded}">...</div>

Vue directives

A typo such as v-iff renders on the server, then stops the page in the browser with an error that names the missing directive. Vue reads any v-* name it does not know as a custom directive, and none is registered under that name:

{# Error: 'v-iff' is not a Vue directive, so Vue looks for
   a custom directive of that name and the page fails in
   the browser. Did you mean 'v-if'? #}
<p v-iff="open">Details</p>

{# Right #}
<p v-if="open">Details</p>

Citry reports a v-* name that is one typing slip from a Vue directive: two neighboring letters swapped, one letter typed twice, or one letter left out, such as v-iff, v-shwo, v-IFF, or v-modle. It also reports a spelled-out v-else-if, such as v-elif or v-elseif. It checks every tag, component tags included, except elements inside <svg> or <math>, or inside an element with v-pre, which Vue does not compile.

A name that is itself a word, such as v-tex, v-mode, or v-one, is not reported. Neither is a typo of v-once or v-memo, because Citry does not support those two directives.

With your application loaded, a custom directive whose name is one typing slip from a Vue directive passes when the component registers it in the directives option of $component({...}). citry check --static, and an editor that has not loaded your application, still report it:

from citry import Component

class Disclosure(Component):
    template = """
        {# Passes: this component registers v-iff #}
        <p v-iff="open">Details</p>
    """
    js = """
        $component({
          props: ["open"],
          directives: { iff: { mounted(el) {} } },
        });
    """

Vue finds v-my-dir under my-dir, myDir, or MyDir, and so does the check. When several components share one template, such as subclasses that inherit it, each of them must register the directive, because the page fails in the one that does not. Citry reports the name when it cannot read the option, such as directives: shared.

A directive that a plugin registers for every component, with Citry.vue.use(plugin), is invisible to the check. For such a directive, set rule_misspelled_directive = "ignore" in the Lint class of the components that use it. This also turns off the c- directive checks for those components.

Misspelled HTML names

The browser raises no error for an attribute, tag, or event name it does not know. A typo such as titel for title leaves the element without its tooltip, and @clik for @click leaves the button without a working listener.

Most of these rules report a name that is one typing slip from a real one: two neighboring letters swapped, one letter typed twice, or one letter left out. The ARIA rule reports every unknown name.

Attribute names

{# Error: 'titel' is not an attribute of <div>, so the
   browser ignores it. Did you mean 'title'? #}
<div titel="Board">...</div>

{# Right #}
<div title="Board">...</div>

A binding is checked by the attribute it sets, so :titel, v-bind:titel, and c-titel are reported too. Letter case does not matter. A c- name that looks like a directive, such as c-fro, is reported as a misspelled directive instead.

These are not checked:

  • names with a hyphen or a colon, such as data-* or hx-*;
  • a binding with a modifier, such as :titel.prop;
  • component tags, <c-element>, custom elements such as <my-widget>, and elements inside <svg> or <math>;
  • <slot>, where a binding is a slot prop.

When a page script really reads an attribute with a reported name, rename it to data-<name>, or set rule_misspelled_attribute = "ignore" for that component.

Element names

The browser renders an unknown tag as an element with no styles or behavior, with no error.

{# Error: <dvi> is not an HTML element. Did you mean <div>? #}
<dvi class="board">...</dvi>

{# Right #}
<div class="board">...</div>

Only a lowercase tag with no hyphen and no c- prefix is checked, and only when it is one typing slip from an HTML element. Any other unknown tag, such as <widget>, is not reported, because a Vue plugin may register a component under that name. If a plugin registers a name that is one typing slip from an HTML element, set rule_misspelled_element = "ignore" for the components that use it.

ARIA attributes

Browsers and screen readers ignore an aria-* name that WAI-ARIA does not define, so the element loses the state or label you meant to give it:

{# Error: ':aria-expandd' is not an ARIA attribute.
   Did you mean 'aria-expanded'? #}
<button :aria-expandd="open">Menu</button>

{# Right #}
<button :aria-expanded="open">Menu</button>

Every unknown aria-* name is reported, not only typos, because ARIA does not let a page invent its own names. The message suggests the closest ARIA attribute when one is close. Bindings such as :aria-* and c-aria-* are checked too. Component tags are skipped, because there the name is an input. To keep a custom value on an element, store it in a data-* attribute.

Event names

{# Warning: 'clik' is not a DOM event, so this listener
   never runs. Did you mean 'click'? #}
<button @clik="toggle()">Menu</button>

{# Right #}
<button @click="toggle()">Menu</button>

This rule is a warning by default, because a page can dispatch events with any name. It checks listeners on HTML elements whose event name is all lowercase letters. A name with a hyphen, a colon, or a capital letter, such as @item-added, is a custom event and is not reported. Neither are scrolled and touched, which are ordinary words. Component tags and custom elements are skipped. For a listener on a component tag, see Component event names.

If the page really dispatches a custom event with such a name, set rule_misspelled_event = "ignore" for that component.

Vue compile errors

Citry compiles a component's Vue code on the server when the component renders. A broken expression, a misplaced v-model, or HTML the browser would rearrange, such as a <div> directly inside a <table>, stops that compiler, so the component fails to render with a ValueError that may not point at the line in your template. The lint rules report these mistakes at their place in the template, before anything renders.

The Vue rules (invalid expressions, v-model targets, Vue directive typos, and DOM event names) skip everything inside an element with v-pre, because Vue does not compile it. The rule for other compile errors still checks how elements nest there, unless Citry also fills something in on the element or inside it, such as {{ title }}, a c- attribute, or a <c-if>. Citry then sends the element's contents to the browser as HTML that Vue does not compile, so that rule skips them too. On a <table>, its rows and sections, or an element inside <svg> or <math>, Citry compiles those contents as usual, so the rule checks them, and they cannot hold Vue syntax.

Invalid expressions

{# Error: The Vue expression in 'v-if' is not valid
   JavaScript (Unexpected token), so Vue cannot compile
   this template. #}
<p v-if="open &&">Details</p>

{# Right #}
<p v-if="open && ready">Details</p>

Citry checks every Vue expression, such as the value of v-if, :title, v-for, or @click, and the arguments of a server call such as @c-click="rate({ stars: 5 })". It decodes character references first, as Vue does, so a &amp;&amp; b passes. A listener may hold statements, such as @click="count++; save()", or a function.

The message names the JavaScript parser's error, and the editor underlines the place it points to, such as the end of open && or the stray ) in go()). An expression that contains a character reference, such as &amp;, is underlined as a whole instead, with no parser error in the message.

It does not check:

  • a :title with no value, which Vue reads as :title="title";
  • anything inside an element with v-pre;
  • a dynamic slot name, such as #[name];
  • the value of a custom directive. A value there that is not valid JavaScript still stops the render; the lint does not report it.

v-model targets

v-model binds the value of an <input>, <textarea>, or <select>. On any other HTML element, the template fails to compile:

{# Error: v-model does not work on <form>, which holds no
   value. #}
<form v-model="query">
  <input type="search" name="q">
</form>

{# Right: bind the input that holds the value #}
<form>
  <input v-model="query" type="search" name="q">
</form>

A custom element such as <my-picker> is reported too. Bind its value property and listen for its change event instead. Component tags, PascalCase Vue components, and <c-element> are not reported, because they decide for themselves what v-model binds.

Other compile errors

A component that uses Vue fails to render when Vue's compiler rejects its template. Citry runs the same compiler over every template and reports what it rejects at the place you wrote it. Most often the browser would build a different element tree from the one your template describes, so in a component without Vue the page still renders, but not as written:

{# Error: Vue cannot compile this template: a <div> inside
   a table must sit in a <td> or <th>, so the browser moves
   it out of the table. Put rows in <tr> and cells in <td>
   or <th>. #}
<table>
  <div>Row</div>
</table>

{# Right #}
<table>
  <tr><td>Row</td></tr>
</table>

The rule also reports:

  • a <button> inside a <button>, a <form> inside a <form>, or an <a> inside an <a>, and the end tag that is then left with nothing to close, such as the second </form>;
  • a v-else or v-else-if with no v-if on the element right before it. Keep a v-if and its v-else on the same side of a <c-if> tag;
  • a component inside a Vue v-for, which only <c-for> can repeat. Only citry --app ... check reports this. It needs your application to tell this component from one with transparent = True or simple = True, which renders into its caller's HTML and so may sit inside a v-for.

Every <c-if>, <c-elif>, and <c-else> branch, and the body of every <c-for>, is checked.

A broken expression is reported as an invalid expression, and a block inside a <p> as a block inside a paragraph. This rule does not report those again, even when you turn their rules off, so each mistake has one message and one setting.

It does not check:

  • anything inside an element with #c-ignore, or inside <c-raw>;
  • the contents of a v-pre element that Citry also fills something into, such as {{ title }}, except on a table, its rows and sections, or inside <svg> or <math> (see above);
  • in most templates, how the content of a <c-if> branch or <c-for> body fits the element around it, such as a <div> in a <c-for> directly inside a <table>, because Vue compiles that content on its own;
  • whether what a <c-element> holds fits the tag Python chooses for it;
  • where a component tag sits, such as a row component inside a <table>;
  • with your application loaded, what you pass to a component with transparent = True or simple = True, which renders into its caller's HTML;
  • attributes an extension handles, such as @c-click;
  • a template that uses an extension's own template syntax.

To turn the rule off for a component, set rule_vue_compile_error = "ignore" in its Lint class.

Component event names

A listener on a child component for an event the child never emits silently does nothing. Vue passes the listener to the child's root element, where it runs only if that element fires a DOM event with that name:

{# Warning: Component 'c-card' does not declare event
   'hdie' in its emits option. Did you mean 'hide'? #}
<c-Card @hdie="hideCard"></c-Card>

{# Right #}
<c-Card @hide="hideCard"></c-Card>

Citry compares each listener on a component tag with the events the child declares in emits, or through an on<Event> prop, and suggests a declared event that is one typing slip away. A DOM event name, such as @click, is not reported, because the child's root element may fire it. Citry checks only when the child's emits is an array of strings or an object whose keys are written as plain names, not computed.

This rule reads each child's emits, so it needs your application: citry --app ... check reports it, and the editor reports it once it has loaded your application. It is a warning by default. To make an undeclared listener fail citry check, set rule_undeclared_component_event = "error". See Emitted event names for the checks on the child's side.

Blocks inside <p>

A <p> cannot hold a block element such as <div>, <ul>, or <h2>. The browser closes the paragraph just before the block, so the page has a different structure from your template, and your CSS may no longer match. In a component that uses Vue, the template fails to compile, so the component fails to render.

{# Error: <div> cannot be inside <p>. The browser closes
   the <p> before it. #}
<p>Owner: <div>{{ owner.name }}</div></p>

{# Right: use an inline element, or make the outer one a div #}
<p>Owner: <span>{{ owner.name }}</span></p>

Citry reports the elements that the HTML Standard says close an open <p>, including <div>, <ul>, <ol>, <table>, <h1> to <h6>, <section>, another <p>, and obsolete blocks such as <center> and <xmp>. It finds them through inline elements such as <span>, custom elements, c-if and c-for blocks, and a <c-slot> fallback.

It does not look inside <button>, <table>, <template>, <svg>, <math>, a component tag, or <c-element>, or inside <noscript>, whose content the browser reads as text when scripts run.

Duplicate ids

An id must be unique in the page. When two elements share one, a label's for, aria-labelledby, a #fragment link, and getElementById find only the first:

{# Error: Another element in this template already has
   id 'board'. #}
<div id="board">
  <h1 id="board">Board</h1>
</div>

{# Right #}
<div id="board">
  <h1 id="board-title">Board</h1>
</div>

Citry reports a literal id only when both elements always render. It skips an element that may render zero or several times: one that has, or sits inside, any of these:

  • c-if, c-elif, c-else, c-for, or c-empty, as a tag or an attribute;
  • v-if, v-else-if, v-else, or v-for;
  • a c-fill, a <c-slot> fallback, or a component tag's body;
  • a <template>.

So c-if and c-else branches may share an id. v-show does not count, because a hidden element is still in the page.

Inside an element with v-pre, Vue leaves v-if and v-for as written and treats a PascalCase tag as a plain element. None of these count there, so both elements of a v-if/v-else pair are in the page and a repeated id on them is reported.

The same id in two different templates is not reported, even when both render on one page. Development mode reports that case when Citry turns the page into HTML; see Repeated ids.

Images without alt text

A screen reader reads out the file name of an <img> that has no alt text, or nothing useful at all, and a broken image shows no text in its place:

<div class="profile">
  {# Warning: <img> has no alt text. #}
  <img src="/static/avatar.svg">
</div>

<div class="profile">
  {# Right: describe the image #}
  <img src="/static/avatar.svg" alt="Ada's avatar">
  {# Right: a decoration that screen readers skip #}
  <img src="/static/divider.svg" alt="">
</div>

An image passes when it has alt in any form (alt, c-alt, :alt, or v-bind:alt), an aria-label or aria-labelledby, or role="presentation" or role="none". An image with a c-bind or v-bind spread is skipped, because the spread may add alt.

The rule is a warning by default. To make it fail citry check, set rule_missing_image_alt = "error".

An <img> that is the template's only top-level element may get its alt from the parent: Vue passes the attributes written on a component's tag to that element when the component has browser code. An <img> directly inside a single top-level c-if, c-elif, and c-else chain counts as that element too. Citry reports such an image only with your application loaded, and only when no parent's alt can reach it: the component has no browser code (no js, js_data(), State, or event handlers), or its JavaScript stops Vue from passing attributes on with inheritAttrs: false:

from citry import Component

class Avatar(Component):
    template = """
        {# Warning: <img> has no alt text. #}
        <img :src="src">
    """
    js = """
        $component({ props: ["src"], inheritAttrs: false });
    """

An inheritAttrs value that Citry cannot read, such as inheritAttrs: settings.inherit, counts as passing alt on, so the image is not reported.

Strict CSP problems

A strict Content Security Policy blocks inline scripts and styles, inline event handlers, and javascript: URLs. The browser skips them, and the page shows no error, only a message in the browser console. When your app sets security_csp to "warn", the editor and citry check report these as warnings. With "strict" they are errors, so citry check fails:

{# Error: A strict Content Security Policy blocks the
   inline event attribute 'onclick'. #}
<button onclick="save()">Save</button>

{# Error: ... blocks the javascript: URL in 'href'. #}
<a href="javascript:void(0)">Open</a>

{# Error: ... blocks this inline <script>. #}
<script>startTour()</script>

{# Right #}
<button @click="save">Save</button>
<a href="/tour">Open</a>

Citry reports:

  • a <script> or <style> element;
  • an attribute with a fixed value (not a binding such as :onclick) whose name is longer than two characters and starts with on, in any letter case;
  • a javascript: URL in action, formaction, href, src, xlink:href, or data on <object>, also when it is written with character references such as java&#115;cript:.

Move a script or style into the component's js or css, or into a Script or Style dependency. Citry also checks the content of <c-raw>, which it writes to the page unchanged, and the element that <c-element is="..."> names.

Citry uses the same rules when it checks a page as it renders it (see Check output for CSP). A page that Vue builds in the browser is the exception: the render-time check never sees what Vue writes, so for such a page this check is the only one.

A custom attribute such as online or onboarding-step is reported too, because browsers and the policy treat every on* attribute as a possible event handler. Rename it, for example to data-online.

The check reads only fixed text in the template. Citry checks Citry bindings such as c-href and c-bind, and HTML passed to a component in an attribute, when it renders the page. Vue bindings such as :href and v-bind get their values in the browser, so neither check sees them.

It skips attributes on component tags, including a capitalized tag such as <Card> that may be a Vue component. It also skips the content of <noscript>, <iframe>, <xmp>, <noembed>, <noframes>, and <plaintext>, which a browser reads as text (a browser with scripting on does so for <noscript>), and markup inside an SVG <title> or <style>, which Citry's template parser reads as text. The check that security_csp runs when Citry renders the page still reports an event handler inside a <noscript>, because Chromium builds those tags as real elements inside a Vue block. Remove the handler from the <noscript>.

The rule follows your app's security_csp setting, so it has no rule_* setting, and a component's Lint class cannot change it. It reports nothing while security_csp is "off", the default, and nothing in citry check --static or in an editor that has not loaded your app, because those do not know the setting. Passing security_csp to one serialize() call does not change what the editor and citry check report.

Loops without #c-key

On a page that uses Vue, each component that <c-for> repeats needs a #c-key. Without one, the page fails to render as soon as the loop has two items:

{# Error: <c-Card> repeats inside <c-for> but has no
   #c-key. This page uses Vue, and the render fails
   when the loop has two items. #}
<c-for each="project in projects">
  <c-Card c-title="project.title" />
</c-for>

{# Right #}
<c-for each="project in projects">
  <c-Card
    #c-key="project.slug"
    c-title="project.title"
  />
</c-for>

A page uses Vue when any component on it has component JavaScript, js_data() that returns data, an Events class, or a Vue attribute such as v-if, @click, or :title in its template. Citry reports a repeated component when the component whose template has the loop, or the repeated component, is one of those. It cannot see the rest of the page, so a loop on a page that uses Vue only because of another component is not reported.

A component inside a keyed component, such as <c-Card> in the body of <c-List #c-key="...">, needs no key of its own. A component with transparent = True or simple = True is not reported, because it renders into its caller's HTML. A <c-component> that picks its component at render time needs a key too, but Citry does not check it. This rule needs your application, so only citry --app ... check reports it.

Assignments to props

A component cannot change a prop it receives. Vue keeps the old value and only logs a warning in the browser console, so the button below does nothing:

{# Error: Prop 'open' is read-only, so this assignment
   does not change it. #}
<button @click="open = false">Close</button>

{# Right: ask the parent to change it #}
<button @click="$emit('close')">Close</button>

Citry reads the props from the component's $component({ props }) and reports an assignment to one of them in the component's own template: =, += and the other assignment operators, ++, --, and v-model="open". It reports this.open = false, this.count++, and the other writes through this, or through the component object that $component gives its callback, in the component's JavaScript too, at the severity rule_prop_assignment sets. Changing a field of an object prop, such as open.count = 1, is allowed and not reported.

citry --app ... check reports this rule, and the editor reports it once it has loaded your application.

Server event arguments

The server checks the arguments of an @c-* call against the handler's data class before the handler runs, and rejects the whole call on any mistake. Citry compares the arguments you write in the template with that class:

class SaveIn:
    amount: int

class Counter(Component):
    class Events:
        def save(self, data: SaveIn):
            ...

    template = """
      {# Error: Server event 'save' has no field
         'amont'. Did you mean 'amount'? #}
      <button @c-click="save({amont: 1})">Add</button>

      {# Error: Server event 'save' rejects this value
         for field 'amount': Expected int, got str. #}
      <button @c-click="save({amount: '1'})">Add</button>

      {# Error: Server event 'save' requires field
         'amount', which this call does not send. #}
      <button @c-click="save()">Add</button>

      {# Right #}
      <button @c-click="save({amount: 1})">Add</button>
    """

Citry checks what it can read from the template:

  • each key of an object literal, even next to a ... spread;
  • a literal value, such as '1', true, or null, and both results of a condition such as wide ? 2 : 'all', with the server's own rules. The browser sends the arguments as JSON, so a string is not turned into a number. A handler that accepts GET may get them as a query string, where '2' fits an int field, so a value is reported there only when both ways fail;
  • a required field, when the object has no ... spread and no computed key, such as {[name]: 1}.

A call with no arguments is reported only on an element that cannot contain a form, such as <button>. On a <form>, on an element that may hold one, or for the submit event, the browser may send the form's fields instead. When that binding is an @c-submit on the <form> itself, the form field rules check the fields. A Pydantic data class is not checked, because Pydantic converts values and may read a field under another name.

Each mistake has its own setting: rule_unknown_server_event_field, rule_missing_server_event_field, and rule_incompatible_server_event_field. These rules need your application: citry --app ... check reports them, and so does the editor once it has loaded your application. While a handler or its data class has unsaved changes, the editor stops checking calls to that handler until you save the file.

Form fields

A form whose @c-submit names only the handler, as in search or search(), sends its named controls as the handler's arguments, with or without JavaScript. Citry compares each control's name with the handler's data class:

class SearchIn:
    q: str

class Search(Component):
    class Events:
        def search(self, data: SearchIn):
            ...

    template = """
      {# Error: Server event 'search' requires field
         'q', but no control in this form has that
         name. #}
      <form @c-submit.prevent="search">
        {# Error: The form sends field 'qeury', which
           server event 'search' does not declare. #}
        <input name="qeury" />
      </form>

      {# Right #}
      <form @c-submit.prevent="search">
        <input name="q" />
      </form>
    """

Citry checks each <input>, <select>, <textarea>, and submit <button> with a name written in the template. A submit button sends its name only when it submits the form, and a checkbox only when it is checked, so such a mistake fails only those submits.

Citry leaves out a control that the browser may not send with this form, or may send under another name:

  • a disabled control, including one inside a disabled <fieldset> or with a bound :disabled;
  • a control tied to another form by its form attribute;
  • a file input, a button that cannot submit, and a button whose click is prevented, as in @click.prevent;
  • a control whose type or name is written as an expression, or that has an attribute spread such as v-bind="attrs".

It also leaves out the host's CSRF field, such as Django's csrfmiddlewaretoken, because the server removes it before it checks the data class (CSRF in forms). An image button, <input type="image">, sends where it was clicked as x and y, or go.x and go.y for name="go", so Citry checks those names instead.

A required field without a control is reported only when the template shows every control the form can send. The check is off for a form that holds a component, custom element, slot, <template>, loop, v-html, #c-ignore content, attribute spread, or a name written as an expression. It is also off when the form has an id, because a control elsewhere could join the form with its form attribute.

Each mistake has its own setting: rule_unknown_form_field and rule_missing_form_field. Like the argument rules, they need your application.

Misspelled CSS variables

Each key that css_data() returns becomes a CSS custom property with the same name, such as --accent for the key accent. A typo in var() reads a property that nothing sets, so the CSS property using it gets its inherited or initial value instead:

class Board(Component):
    def css_data(self, kwargs, slots):
        return {"accent": "blue"}

    css = """
      h1 {
        /* Warning: Nothing sets --acent, so this
           property gets its initial or inherited
           value. Did you mean --accent, from
           css_data()? */
        color: var(--acent);
      }
    """

Citry reports a var(--name) in the component's own CSS only when the name is one typing slip from a css_data() key, so a variable that a site stylesheet or a parent component sets is left alone. A var() with a fallback value, such as var(--acent, blue), and a property the same CSS sets itself are not reported, and neither is a component whose css_data() keys Citry cannot all read. The rule is a warning by default and needs your application, so only citry --app ... check reports it. To find every var() that nothing sets, turn on unset CSS variables.

Misspelled CSS classes

A typo in a class attribute leaves the element without its styles, and the browser does not say why:

class Board(Component):
    template = """
      {# Warning: No CSS that Citry reads styles the
         class 'bord'. Did you mean 'board', from this
         component's CSS? #}
      <div class="bord"></div>
    """

    css = """
      .board {
        display: grid;
      }
    """

The CSS that Citry reads is, for every component your app registers:

  • its css or css_file;
  • the stylesheets in its Dependencies that are inline, such as Style(content=...), or local files; not a stylesheet linked by URL;
  • the <style> elements in its template that hold CSS, not another language such as lang="scss".

Citry reports a class in a static class attribute, one written as plain text, when no CSS that Citry reads styles it and it is one typing slip from a class that the component's own css or css_file styles. A typing slip is two neighboring letters swapped, one letter typed twice, or one letter left out.

A class on a component tag is checked too: the component receives it as an input and usually puts it on one of its elements.

These are not checked:

  • a class set by :class or c-class;
  • the words inside {{ }} in a class attribute. Citry shows a plain attribute's text exactly as written, so use c-class for a value that changes;
  • a class shorter than three characters;
  • a class on a tag that renders no element of its own, such as <c-if> or <template>;
  • a slip that usually names another class of the same family, such as col-1 next to .col-12 or tab next to .tabs. See Similar class names for the full list.

The rule is a warning by default. Only citry --app ... check reports it; the editor does not. If a stylesheet that Citry does not read styles the class on purpose, set rule_misspelled_css_class to "ignore" in that component's Lint class (Override one component).

Classes without CSS

This rule is off by default. Turn it on to find every class in a template that no CSS styles, such as a class whose rule you deleted:

app = Citry(
    lint=LintSettings(
        rule_undeclared_css_class="warning",
    ),
)

citry --app ... check then reports each class in a static class attribute that the CSS Citry reads does not declare. A class that the misspelled class rule reports is not reported again:

{# Warning: No CSS that Citry reads styles the
   class 'card-header'. #}
<div class="card-header">Title</div>

Like the misspelled class rule, it skips bound classes, the words inside {{ }}, and classes on tags that render no element. Unlike that rule, it also checks classes shorter than three characters. The editor does not run it.

The rule also reports classes that work, which is why it is off by default:

  • classes from a stylesheet linked by URL or with a <link> tag, such as a site stylesheet or a CSS framework;
  • utility classes that a build tool such as Tailwind generates;
  • classes used only by JavaScript or by tests, such as js-toggle;
  • classes styled by a stylesheet written in another language, with css_lang or a template <style lang="...">, or in a local file that is not UTF-8 text;
  • the classes of a component library you install, which you cannot change.

To check only your own components, leave the rule off in LintSettings and turn it on in their Lint class:

class Board(Component):
    class Lint:
        rule_undeclared_css_class = "warning"

Or turn it on for the app and set it to "ignore" in the Lint class of each component that uses a CSS framework.

What declares a class lists the selectors that count.

Unset CSS variables

This rule is off by default. Turn it on to find every var(--name) that reads a custom property nothing sets:

app = Citry(
    lint=LintSettings(
        rule_undeclared_css_variable="warning",
    ),
)

With the rule on, Citry reports a var() that nothing sets:

class Card(Component):
    css = """
      .card {
        /* Warning: Nothing that Citry reads sets
           --card-gap, so this property gets its
           initial or inherited value unless a
           stylesheet or script outside Citry
           sets it. */
        padding: var(--card-gap);
      }
    """

Citry checks each var(--name) in a component's own css or css_file that has no fallback value; var(--card-gap, 1rem) is never reported. It counts these as setting --name:

  • a --name: value declaration or an @property --name rule in the CSS Citry reads;
  • a css_data() or CssData key called name on any component. Citry sets each key on that component's root element, and everything inside it, other components included, inherits the value;
  • a style attribute in a template that sets --name;
  • the text --name in quotes, or followed by a colon, in a :style or c-style binding, in a component's JavaScript, or in the Python module that defines a component, as in setProperty('--name', value) or f"--name: {value};".

A var() inside a template's style attribute is not checked. A component whose css_data() keys Citry cannot all read is skipped, because it may set any property, but a property that only such a component sets is still reported where another component reads it. A var() that the misspelled CSS variable rule reports is not reported again. The editor does not run this rule.

The rule also reports properties that a site stylesheet, a design system, or a script outside Citry sets, which is why it is off by default. Set it to "ignore" in the Lint class of a component that reads such properties, or turn it on only in the components you want checked.

A misspelled link, a wrong route parameter, or a misspelled file name shows up only as a 404 page when someone opens it. Citry reports these links as citry.template.unknown-url:

{# Warning: Your app has no route or static file
   for '/abuot', so the browser gets a 404 Not
   Found. Did you mean '/about'? #}
<a href="/abuot">About</a>

{# Warning with Flask's /projects/<int:id> route #}
<a href="/projects/alpha">Project</a>

{# Warning: Did you mean '/static/avatar.svg'? #}
<img src="/static/avtar.svg" alt="" />

Load your routes

Citry does not know your app's routes. The function you mount Citry with lets it ask your web framework whether it serves each path:

FunctionWhat it checks
citry.contrib.flask.mount()Flask's URL rules, and the files in the app's and blueprints' static folders
citry.contrib.fastapi.mount()The routes of a FastAPI or Starlette app, and the files in its StaticFiles mounts
citry.contrib.django.urlpatterns()Django's URL patterns, and the files Django's static file finders find under STATIC_URL

citry check and the editor learn your routes only when that function runs while they import your app. Point --app at the module that mounts Citry, not only at the module that creates the Citry instance:

# app/main.py calls mount(app, citry_app)
citry --app app.main:citry_app check

For Django, point --app at the URL configuration that calls urlpatterns(), such as config.urls:citry_app. That module must import your Citry instance under the name after the colon. Set DJANGO_SETTINGS_MODULE when you run the check, and in the editor's env file (citry.envFile in VS Code, envFile in PyCharm). Citry then starts Django before it imports the URL configuration, so your views can import models.

A Flask app built by a factory function mounts Citry only when the factory runs. Add a module that calls the factory, and point --app at it (app.wsgi:citry_app):

# app/wsgi.py
from app import create_app
from app.citry_app import citry_app

web_app = create_app()

For every framework, give the editor the same --app path in its settings: citry.app in VS Code, app in PyCharm. The FastAPI, Django, and Flask starter projects use these paths.

If none of these functions ran, citry check prints one note and checks no links, and the editor checks no links either. Serving Citry with the plain ASGI or WSGI app from citry.contrib.asgi or citry.contrib.wsgi leaves links unchecked, because those apps do not know your routes.

The rule checks a literal href, src, or action on an HTML element when the value starts with a single /. The query string and fragment are ignored, so /about?tab=team#people is checked as /about. These are not checked:

  • a URL with a scheme, such as https: or mailto:, and a //cdn.example.com/... URL;
  • a relative path, such as page.html;
  • a value written as an expression, such as :href or c-href;
  • an attribute on a component tag, which is a component input, or on a custom element such as <my-widget>;
  • srcset, which can hold several URLs, <base href>, and a <link> with rel="preconnect" or rel="dns-prefetch";
  • a path under the prefix Citry's own routes are mounted at, such as /citry/citry.js;
  • a route parameter whose type only your view function checks, such as project_id: int on FastAPI's /projects/{project_id}. The route matches any text, so /projects/alpha counts as served;
  • with Django, a path under MEDIA_URL, because uploaded files are not listed anywhere Citry can read.

When your app is served below a sub-path, such as /shop, its links start with /shop, as in /shop/cart, but its routes leave it out, as in /cart. Citry removes /shop from each link before it asks your framework. It reads the sub-path from your framework's own setting:

FrameworkWhere you set it
FastAPIFastAPI(root_path="/shop")
Flaskapp.config["APPLICATION_ROOT"] = "/shop"
DjangoFORCE_SCRIPT_NAME = "/shop" in settings.py

A link that does not start with the sub-path, such as /blog, is reported, because the browser sends it outside your app. A path under Citry's own prefix, listed above, is not checked.

Write the value with a leading /, such as /shop; a trailing / is ignored, and an empty value or / means the site root. Citry reads the value the same way when it builds its own URLs, so a value that does not start with a single /, such as shop, also counts as the site root (see Serve below a sub-path).

If only your server sets the sub-path, such as gunicorn's SCRIPT_NAME or uvicorn's --root-path, the check cannot see it and reports every link that includes it. Set the same value in the framework setting above, or turn the rule off for that app. A plain Starlette app has no such setting, so turn the rule off there. In Flask, APPLICATION_ROOT also sets the path of the session cookie, which then matches the sub-path, unless you set SESSION_COOKIE_PATH.

If only your server sets the sub-path, Citry reports correct links that start with it; see the sub-path rules above for the fix.

Citry also reports a path that another server answers, such as a reverse proxy in front of your app. That is why the rule is a warning by default.

The editor checks links when it loads your app, so a link you add later is checked after the next load. VS Code reloads the app when a Python file or the env file changes; saving a template file does not reload it. To recheck sooner, run Citry: Restart Language Server.

If your framework raises an error while Citry asks about a link, citry check skips that link and prints one note with the error. The editor does not report such a link and shows no message. It also stops asking after 3 seconds in total and leaves the remaining links unchecked, so a slow app does not hold up the editor.

To turn the rule off, set rule_unknown_url to "ignore" in the Lint class of the component that holds the link (Override one component), or in LintSettings for the whole app.

Keys nothing provides

A component that reads a shared value with self.inject() under a key that nothing above it provides fails with KeyError when the page renders. Here the page provides board, and the card reads bord:

<c-provide key="board" name="Projects">
  <c-card />
</c-provide>
class Card(Component):
    def template_data(self, kwargs, slots):
        # Warning: No component above Card provides
        # 'bord', so self.inject('bord') raises
        # KeyError when the page renders. Did you
        # mean 'board'?
        board = self.inject("bord")
        return {"board_name": board.name}

Citry starts at each template that uses the component's tag, such as <c-card />, and walks up through the templates that use those components, to the top of the page. A key counts when:

  • a <c-provide key="..."> wraps the tag;
  • a component on the way calls self.provide() with it;
  • the tag is slot content, and the component whose <c-slot> shows it wraps that <c-slot> in <c-provide> or calls self.provide();
  • a <c-component c-is="..."> sits inside a <c-provide> with the key, or in a component that calls self.provide() with it, because it may render any component;
  • a render(provides={...}) call in your project's Python files passes it as a literal key. Such a key counts for every component.

If the component appears in several places and one of them provides the key, Citry reports nothing. A key written as a module-level string constant, such as self.provide(BOARD_KEY, ...) or render(provides={BOARD_KEY: ...}), counts as that string, also when the module imports BOARD_KEY from another module of your project.

When no template uses the component's tag, Citry compares the key with every key your app provides anywhere, and the message starts with "Nothing in your app provides". That happens when Python renders the component, or when a <c-component c-is="..."> picks it. It also happens for a component used only by templates that use each other and that no other template uses, such as a tree that renders itself.

Citry checks a self.inject() call that has one string literal and no default, in the component's class or in a class or mixin it extends. A call in a base class that several components extend is reported once, and only when none of them gets the key; for a mixin, the message names one of the components that use it. These calls are not checked:

  • a call with a default, such as self.inject("theme", None), because the key may be missing on purpose;
  • a key written as a name or an expression, such as self.inject(BOARD_KEY) or self.inject(key_name);
  • a call in a helper function outside the class;
  • a call in a class from an installed package, which you cannot change.

Citry reports nothing for a component when the way up to it goes through something it cannot read:

  • a <c-provide c-key="...">;
  • a self.provide() key written as an expression;
  • a tag inside a <c-component c-is="...">;
  • markup passed in a component's attribute, such as c-body="<>...</>";
  • a component that Python builds inside a component's methods, or passes to another component, such as Layout(slots={"default": Widget()}), directly or through a variable. Your test files are not read for this;
  • a component whose Python source Citry cannot read and whose code calls provide().

Such a component also stops Citry from reporting a component no template uses. While a registered template cannot be parsed, or when the folder you run citry check from holds more than 20,000 Python files, the rule reports nothing at all.

Citry also reports a key the page does provide when it cannot see the provider: a provides dictionary built elsewhere, such as render(provides=shared); a self.provide() call in a helper function; a template written as a Python string and rendered from Python; or a render(provides=...) call outside the folder you run citry check from. That is why the rule is a warning. To turn it off, set rule_unknown_inject_key to "ignore" in the component's Lint class (Override one component), or in LintSettings for the whole app.

The editor checks the self.inject() calls in the file you are editing against the keys your app provided when it last loaded. A call you type in an existing component is checked at once. A new component, or a provider you add, counts after the next load, which VS Code starts when you save a Python file.

Check rules in CI

Run the check against your application, so it knows every component and reads your LintSettings and each component's Lint class:

citry --app myproject.app:app check

Warnings are printed, and included in --format json output, but do not fail the command. Any error exits with status 1. See Command line.

Less common cases

Without a loaded app

citry check --static, and an editor that has not loaded your application, do not know every component's template data. They skip the unknown-name rules, the component event rule, which reads each child's emits, and the rules for repeated components, prop assignments, server event arguments, misspelled CSS variables, misspelled CSS classes, classes without CSS, unset CSS variables, links, keys nothing provides, and strict CSP problems, which needs your app's security_csp.

They still run every rule that reads only the template: the Alpine, attribute-value, and misspelled-directive rules, and the rules for misspelled HTML names, Vue compile errors, blocks inside <p>, duplicate ids, and images without alt text. An <img> that is a template's only top-level element is never reported there, because these tools cannot tell whether the component has browser code.

They cannot read your LintSettings, but they do read the Lint class of the component that declares an inline template, without running your code:

  • A rule set to a plain string, such as rule_misspelled_directive = "ignore", applies as written.
  • A Lint inherited from a component class in the same file applies too, and Lint = None drops it, as with a loaded application.
  • A subclass in the same file whose only base is that component, and that sets neither template nor template_file, renders the same template. The strictest severity among those components applies, as in shared templates.

A rule keeps its default severity when neither the component nor a component class it inherits from in the same file sets it, or when the value cannot be read from the source: a name imported from another module, a value computed at run time, a Lint class with its own base class, or a Lint assigned inside an if. In the editor, a template file, and a template whose closing quotes are not typed yet, use the defaults too, because no Lint class can be read for them. The one exception to the defaults: an invalid attribute value is a warning there, so a value that a page script reads cannot fail the check when only LintSettings turns the rule off.

To keep a name that is really meant for the browser out of the check, pass it through c-bind. These tools also cannot tell which values an extension's template syntax produces, so they may report a value that citry --app ... check does not.

Imported base classes

When a component extends a class from another module of your project, the file alone does not show that the class is a component:

from app.base import BaseCard

class Card(BaseCard):
    template = """
      <article>{{ title }}</article>
    """

citry --app ... check, with or without --types, and an editor that has loaded your application find Card among your registered components and check its template.

Without your application, Citry skips the template. citry check --static lists each skipped template as a note, and the editor marks the class name with an information message (citry.check.template-not-checked). Nothing is wrong with the code. To have the editor check the template, give it your application, for example with the citry.app setting in VS Code.

The editor finds these classes by the names they had when it loaded your application. A class you add or rename keeps the message until the editor loads your application again, which VS Code does when you save a Python file.

Shared templates

When several components use the same template or JavaScript file, Citry applies the strictest severity among them. To silence a rule for that file, every one of those components must set it to "ignore". The server event argument rules check a call in a shared template only when all those components use the same data class for its handler.

Data with extra keys

How strict the unknown template variable rule can be depends on the component's template data schema:

Template data schemaSet to errorSet to warningSet to ignore
Closederrorwarningnothing
Pydantic with extra="allow"warningwarningnothing
Unknown or noneerrorwarningnothing

A Pydantic schema that allows extra keys may receive any name at runtime, so Citry reports an undeclared name as a warning, not an error. Plain classes, dataclasses, NamedTuples, and Pydantic models that ignore or forbid extra keys are closed.

Similar class names

The misspelled class rule does not report a slip that usually names another class of the same family:

  • a moved, doubled, or dropped digit, such as col-1 next to .col-12;
  • a missing final s, such as tab next to .tabs, unless the class already ends in s, as progres next to .progress does;
  • one of these short words next to its longer form, as the whole class or as its last word after a hyphen or underscore, such as navbar-toggle next to .navbar-toggler: close (closed), collapse (collapsed), disable (disabled), enable (enabled), fade (faded), mute (muted), show (shown), slide (slider), and toggle (toggled or toggler). Any other word missing its last letter, such as heade next to .header, is reported;
  • one letter typed twice or left out in a first part of one or two characters before a hyphen, such as p-4 next to .px-4 or m-auto next to .ml-auto. Two letters swapped there, such as iu-button next to .ui-button, are reported.

What declares a class

For the CSS class rules, a selector declares a class wherever it names it: .name, .card .name, .name:hover, :is(.name), and inside @media or a nested rule. An attribute selector such as [class~="name"] declares it too, and [class^="btn-"] declares every class that starts with btn-. A class in a comment, a string, or a property value does not count. As in a browser, an unclosed comment runs to the end of the stylesheet, so no class after it counts.

Mixins and extends

The unknown member check needs every name the component defines. When the component's Vue Options use mixins or extends, those names are not in the source, so Citry skips the check. A Python loop variable read by Vue is then reported as the citry.vue.python-variable warning.

Unchecked attributes

The attribute-value check does not look at a bound value that is not one string, such as :dir="direction" or c-dir, or at a binding with a modifier such as .prop. It also skips component tags, <c-element>, custom elements such as <my-widget>, elements inside <svg> or <math>, and attributes that take a list of words, such as rel, sandbox, or autocomplete on <input>.

For type on <ol> and <li>, letter case matters: "a" and "A" are different list markers.

When the editor or citry check --types also runs TypeScript, a bound value that Vue's types reject is reported once, by this rule, at this rule's severity.

Window names, meta tags

target and formtarget accept any window name, so Citry checks only names that start with an underscore. The valid ones are _blank, _self, _parent, and _top, so target="_new" is reported. The name of an <iframe> or <object> may not start with an underscore at all.

http-equiv on <meta> is checked against the values browsers act on: content-type, default-style, refresh, x-ua-compatible, and content-security-policy. Browsers ignore a header name such as Cache-Control there, so the message says to send it as an HTTP header:

{# Error: browsers ignore this; send Cache-Control as a header. #}
<meta http-equiv="Cache-Control" content="no-cache">

Alpine load errors

An Alpine-only event modifier such as @click.away, and v-once or v-memo, are not lint rules, so no setting turns them off. The template fails to load, with a message that shows what to write instead. See What is not supported.

In the editor, go to definition on a name declared in template_variables opens its key in your LintSettings, when the settings are written directly in the Citry(...) call or through a simple variable. A name declared in a component's Lint class opens that class, including an inherited one. Settings built by a function still work, but have no definition to open.

Extension variables

An extension that adds template variables can describe them with TemplateNamespaceContribution, so Citry knows them. It can list the names, or say that it adds names it cannot list. It cannot lower the severity your application chose.