Developing packages

Package components, themes, or icon sets for other labb projects. A consumer reads templates and styles from installed Python packages, including labb itself.

Read Building CSS first if the scan and build pipeline is new to you.

What a package ships

A labb package is an installable Python package containing some of the following files.

• Templates under templates/cotton/<ns>/ and optional page or example templates
• CSS such as themes under a directory like css/
• labb-provides.yaml, which publishes named CSS groups

my_pack/
  __init__.py
  labb-provides.yaml
  templates/
    cotton/
      mypack/
        card.html
  css/
    theme.css

Step 1: build your components

Write components with django-cotton as you would in an app. A package component can compose labb components. The consumer’s build finds those classes through your components group.

labb resolves component variant classes from usage. Tailwind compiles raw utility classes that it can scan literally. CSS groups cover both kinds of template output.

Step 2: publish CSS groups

Add labb-provides.yaml at the package root. Each group can list components for usage scanning, literals for Tailwind @source files, and imports for CSS included in the build.

provides:
  components:
    components: [templates/cotton/mypack/**/*.html]
    literals:   [templates/cotton/mypack/**/*.html]
  theme:
    imports: [css/theme.css]

• Put templates that use <c-lb.*> components under components. The scanner reads labb’s schemas and resolves component props such as variant="primary".
• Put templates containing raw utility classes under literals. You can list the same glob in both groups because labb de-duplicates it.

labb scan currently understands labb’s schemas only. It cannot infer that <c-mypack.card variant="fancy"> needs mypack-card-fancy. Until package schemas arrive, list your own component templates under literals and include dynamic classes in a plain text file.

provides:
  components:
    literals: [templates/cotton/mypack/**/*.html, mypack-classes.txt]

@source reads plain text, one class per line. Put shippable CSS such as themes and keyframes under imports. A daisyUI @plugin "daisyui/theme" block must be imported so it resolves in the consumer’s project.

See the labb-provides.yaml reference for the full schema.

Step 3: package and distribute

Distribute the package as you would any Python package. Make sure these two requirements are met.

1. Include labb-provides.yaml, templates/**, and css/** as package data. They are not Python modules and will otherwise be missing from the wheel.
2. Use an importable module name in css.packages because labb resolves it with import <name>.

Then publish to PyPI (or a private index, or use a path/VCS dependency during development).

Step 4: how a consumer uses it

The consumer installs the package, adds it to INSTALLED_APPS when it ships templates, and subscribes to its groups.

# their labb.yaml
css:
  packages:
    labb:   [themes, components]
    my_pack: [theme, components]

On the next labb build, labb imports my_pack, reads labb-provides.yaml, and adds the groups to .labb/labb.css. Consumers do not need to know your internal paths.

Testing your package locally

During development, add the package as a path dependency in a test project.

# in a consumer project
labb build            # resolves your package, regenerates .labb/labb.css

A bad package name or group causes the build to fail with an error.

Related