Somnio Starter

Flutter Somnio Starter made with Mason.

Install

mason add -g somnio_starter_template --git-url https://github.com/somnio-software/somnio-starter --git-ref=templates --git-path somnio_starter_template

How the repository works

This repo uses two branches:

• main — Source of truth. It contains the example app (somnio_starter_example/) and the generator (tool/generator/). All edits to the template content happen here.
• templates — Holds the generated Mason brick that users install with the command above. This branch is updated automatically by a GitHub Actions workflow; you do not edit it by hand.

When you push changes to main that touch the example or the generator, a workflow runs, regenerates the brick, and opens a pull request. Merging that PR updates the templates branch so new and existing users get the latest template.

flowchart LR
  main[main branch]
  workflow[generate_somnio_starter_template]
  pr[PR to chore/generate branch]
  templates[templates branch]
  main --> workflow
  workflow --> pr
  pr -->|"squash and merge"| templates

Loading

Updating the template (for maintainers)

What triggers an update

The workflow generate_somnio_starter_template runs when:

• There is a push to main that changes files under tool/generator/** or somnio_starter_example/**, or
• You run it manually from the Actions tab (workflow_dispatch).

What the workflow does

1. Runs the Dart generator (dart tool/generator/main.dart), which copies the example app and repo .github into the brick and replaces fixed names with template variables.
2. Checks out the templates branch and replaces the current somnio_starter_template/__brick__/ content with the new output.
3. Opens a pull request from branch chore/generate-somnio-starter-template with the commit message "chore: generate somnio_starter_template".

What you need to do

1. Review the opened PR (from chore/generate-somnio-starter-template into templates).
2. Squash and merge the PR. That updates the templates branch, so the published template (used when people run mason add ... --git-ref=templates) is up to date.

To regenerate without pushing to main, go to Actions → generate_somnio_starter_template → Run workflow.

Updating your project from the template (for users)

If you already created a project with this brick and want to pull in the latest template changes:

1. Update the brick so Mason has the latest version:

   • Run mason get if the brick is already in your global config, or
   • Add it again with the same options:
     mason add -g somnio_starter_template --git-url https://github.com/somnio-software/somnio-starter --git-ref=templates --git-path somnio_starter_template

2. Re-run generation in your project directory with the same variables you used initially (e.g. project_name, flutter_version, app_name, reverse_domain, etc.). Use --on-conflict to control overwrites:

   • overwrite — replace existing files with the template version.
   • skip — keep your existing file.
   • prompt — ask for each conflict (default).

   Example (adjust variables to match your project):

   mason make somnio_starter_template --project-name my_app --flutter-version "3.41.2" --on-conflict overwrite

3. Review changes, especially under .github/workflows/. The template may add or change workflow files; the main CI workflow is named after your project (e.g. my_app.yaml) and uses paths relative to the repo root.

GitHub workflows in generated projects

Generated projects include workflows under .github/workflows/ that come from the template. These typically include:

• A main CI workflow named after your project (e.g. my_app.yaml) that runs on pull requests when lib/**, test/**, packages/**, or pubspec.yaml change.
• Other workflows as defined in the template (e.g. token_provider, api_client, auth_client, app_ui, form_inputs, user_repository, spell_checker).

Workflows are parameterized with your project name and use paths relative to the repository root (no working_directory). When you update your project from the template, new or changed workflow files may appear; review and merge them so your CI stays in sync with the template.