Skip to content

Sharing a Project as a Template

Templates are Whittl's project-sharing format. A .whittl-template file packages a project's code, assets, and metadata into one portable file that anyone with Whittl can import.

Useful for:

  • Sharing starter kits with collaborators
  • Saving a well-structured project as a starting point for your own future projects
  • Distributing boilerplate (an app shell with themes / routing / etc. pre-configured)
  • Teaching or demonstrating Whittl-generated patterns

Saving a template

  1. Right-click the project in the sidebar → Save as Template
  2. Or File → Save as Template with the project currently open

The Save Template dialog appears:

  • Template name — what others see when they import
  • Description — a sentence or two explaining what it is
  • Category — Utility / Productivity / Game / Media (for organization in the New Project picker)
  • Include assets? — toggle for whether assets/ goes in the template (usually yes)

Click Save. The template lands in ~/.whittl/templates/ and appears in the My Templates tab of the New Project dialog.

Exporting to a shareable file

Once saved to your local library, you can export as a .whittl-template file:

  1. File → Export Template → pick the template from your library
  2. Choose a destination path
  3. Whittl writes a .whittl-template file (a zip archive internally)

Share the .whittl-template file however — email, Discord, GitHub release, file host. The recipient imports it in their own Whittl.

Importing a template someone shared

  1. Double-click the .whittl-template file (Whittl registers the file association during install), or
  2. File → Import Template → browse to the file

Whittl unzips the template to your local library. It now appears in your My Templates tab alongside any you've created yourself.

To use it: + New → My Templates tab → select → Create.

What's in a template

A .whittl-template file is a zip archive containing:

  • All project files (main.py, ui/, core/, etc.)
  • assets/ folder (if you included it)
  • README.txt for the project
  • A template.json metadata file with name, description, category, creation date

What's NOT in a template

Deliberately excluded:

  • archives/ — version history. Templates start fresh.
  • data/ — runtime data. The template user shouldn't inherit your saved state.
  • project.json — your specific project's ID and metadata. The new project gets a fresh ID.
  • _whittl_launcher.py — regenerated on first run.
  • API keys or secrets — never serialized into templates. Whittl scans for common key patterns and warns if it detects one in source code.
  • Your chat history — the conversation that produced the project doesn't go along.

Security note

When you import a template from someone else, you're importing their code. Whittl doesn't sandbox template code — once imported, it runs with the same privileges as any other project you've written yourself.

For untrusted sources: inspect the main.py and any dependencies before running Test Run. Specifically look for:

  • Imports of os, subprocess, shutil — common in legitimate apps but could be used maliciously
  • Network calls to unfamiliar URLs
  • File writes outside the project folder

For templates from people you trust or from established sources, this is low-priority. For random files from Discord / forums, skim the code first.

Template categories

The category field maps to tabs in the New Project dialog:

  • Utility — calculators, converters, data viewers, small tools
  • Productivity — note-taking, todo, time tracking
  • Game — anything that targets game loops, sprites, input handling
  • Media — image viewers, music players, video tools

Pick the one that fits. If nothing fits, pick Utility. The category is just for organization; it doesn't change how the template works.

Updating a template

To refresh a template with newer code:

  1. Open the project the template was made from
  2. Make your changes, verify it works
  3. Right-click project → Save as Template
  4. The Save dialog recognizes the existing template and offers Update existing (vs create a new one)

The updated template appears in your library with a new modification date. Previously-imported instances aren't affected (they're independent projects).

Publishing a template to the community

There's no public Whittl template gallery yet. Users share templates via:

  • Personal websites / itch.io
  • Discord communities / Reddit

A centralized Whittl template gallery is on the v2.6+ roadmap but not yet built.

Why share templates?

Concrete reasons:

  • Reduce first-generation cost. A well-structured template means the AI doesn't have to invent an architecture from scratch — it starts with good bones.
  • Distribute patterns. If you've figured out a clean way to do audio playback in Flet, a template captures that for everyone who starts from it.
  • Teach Whittl. A template is the best way to show someone "here's what a polished Whittl project looks like."

What's next