mealie - Moses Yebei

mealie

Abstract

Mealie is a self hosted recipe manager and meal planner with a RestAPI backend and a reactive frontend application built in Vue for a pleasant user experience for the whole family. Easily add recipes into your database by providing the url and mealie will automatically import the relevant data or add a family recipe with the UI editor

The Problem

Families want a single place to store recipes, plan meals, and generate shopping lists without relying on commercial SaaS. Manual spreadsheets or disparate tools lack automatic recipe import, API integration, and local hosting.

What This Does

Mealie is a full stack solution: a FastAPI‑based REST backend (mealie/ folder) and a Nuxt 3 reactive frontend (frontend/).

Import recipes automatically from URLs or via the UI editor (frontend/app/components/Domain/Recipe/RecipeActionMenu.vue).
Plan weekly meals (frontend/app/components/Domain/Mealplan/MealPlanLayout.vue).
Create shopping lists grouped by grocery sections (frontend/app/components/Domain/Household/HouseholdPreferencesEditor.vue).
Group recipes into cookbooks (frontend/app/components/Domain/Cookbook/CookbookPage.vue).
Expose a documented OpenAPI spec for integrations (dev/code-generation/main.py generates TS types from the spec).

How It Is Wired

Startup – docker/docker-compose.yml defines mealie-backend and mealie-frontend. The backend service runs docker/entry.sh, which executes ``bash uvicorn mealie.main:app --host 0.0.0.0 --port 8000 ` (mealie/main.py imports routes from mealie/api.py`).
API Layer – mealie/api.py registers FastAPI routers (e.g., /recipes, /mealplans). Each router imports SQLAlchemy models from mealie/models.py and uses Pydantic schemas from mealie/schemas.py.
Frontend Calls – frontend/app/composables/api/index.ts wraps fetch calls to the backend. The composable is used by all domain components.
Data Flow – A recipe import triggers POST /recipes/import, handled in mealie/api.py. The handler fetches the URL, parses content via mealie/utils/recipe_parser.py, creates a Recipe model, and writes it to the database.
OpenAPI Generation – dev/code-generation/main.py reads the OpenAPI spec produced by FastAPI, then writes TypeScript types (frontend/types/) and route helpers (frontend/app/composables/routes/index.ts).

The backend’s “hub” is mealie/api.py; it touches the database, the parser, and the OpenAPI spec. Any change to route definitions cascades to the frontend typings, so maintainers should edit api.py carefully.

How To Use It

# Clone
git clone https://github.com/moses-y/mealie

# Build & run containers
cd mealie
docker compose -f docker/docker-compose.dev.yml up --build

The dev Compose file mounts frontend/ and starts the Nuxt dev server on http://localhost:3000. For a production image:

docker compose -f docker/docker-compose.yml up -d

Configuration is via environment variables defined in .env.example (copy to .env). To run tests:

# Backend
pytest -q tests/

# Frontend
cd frontend
pnpm install
pnpm test

Real‑World Use

A family installs Mealie locally, imports a recipe from a cooking blog, then schedules it for Monday, Wednesday, and Friday. After a week, the shopping list is exported to a CSV and shared with the grocery app. A webhook (frontend/app/components/Domain/Group/GroupWebhookEditor.vue) posts the list to a home‑assistant instance for automatic inventory tracking.

Code Health & Issues

CI – GitHub Actions workflows (.github/workflows/*) run linting, unit tests, and e2e tests.
Tests – 296 test files cover both backend (tests/) and frontend (tests/e2e/).
Static analysis – No structural red flags reported.
Licensing – AGPL‑3.0+ (LICENSE).
Documentation – Extensive docs under docs/, including migration and API guides.

The Bottom Line

Mealie delivers a self‑hosted, feature‑rich recipe and meal‑planning platform with a clean separation between a FastAPI backend and a Nuxt frontend. The repository is well‑structured, CI‑enabled, and fully containerized, making it suitable for teams that need a controllable, open‑source kitchen hub.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,668 files

Python659
TypeScript297
JSON239
Vue229
Markdown49
YAML37

ReactVueDjangoFlaskDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["mealie 448 modules"] g1["frontend 297 modules"] g2["tests 176 modules"] g3["dev 15 modules"] g4["docs 2 modules"] g2 -->|420| g0 g3 -->|4| g0

Module dependencies

The 10 most depended-upon modules of 938, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_tests_utils_fixture_schemas["fixture_schemas"] n1_tests_utils___init__["__init__"] n2_mealie_schema_recipe_recipe["recipe"] n3_tests_utils_factories["factories"] n4_e_schema_response_pagination["pagination"] n5_mealie_core_config["config"] n6_lie_repos_repository_factory["repository_factory"] n7_ema_recipe_recipe_ingredient["recipe_ingredient"] n8_mealie_db_models__model_base["_model_base"] n9_alie_schema__mealie___init__["__init__"] n6_lie_repos_repository_factory --> n7_ema_recipe_recipe_ingredient n2_mealie_schema_recipe_recipe --> n5_mealie_core_config n2_mealie_schema_recipe_recipe --> n9_alie_schema__mealie___init__ n2_mealie_schema_recipe_recipe --> n4_e_schema_response_pagination n2_mealie_schema_recipe_recipe --> n7_ema_recipe_recipe_ingredient n7_ema_recipe_recipe_ingredient --> n9_alie_schema__mealie___init__ n7_ema_recipe_recipe_ingredient --> n2_mealie_schema_recipe_recipe n7_ema_recipe_recipe_ingredient --> n4_e_schema_response_pagination n4_e_schema_response_pagination --> n9_alie_schema__mealie___init__ n1_tests_utils___init__ --> n3_tests_utils_factories n1_tests_utils___init__ --> n0_tests_utils_fixture_schemas n0_tests_utils_fixture_schemas --> n6_lie_repos_repository_factory classDef cyc stroke:#ef4444,stroke-width:2px; class n1_tests_utils___init__,n2_mealie_schema_recipe_recipe,n5_mealie_core_config,n6_lie_repos_repository_factory,n7_ema_recipe_recipe_ingredient cyc;

Dependencies

9 of 83 declared dependencies are a major version behind. Resolved 82 of 83 against the registry.

Package	Declared	Latest	Behind
`marked`	^15.0.12	18.0.9	3 major
`@vueuse/core`	^12.7.0	14.4.0	2 major
`lint-staged`	^15.4.3	17.3.0	2 major
`typescript`	^5.3	7.0.2	2 major
`@vite-pwa/nuxt`	^0.10.6	1.1.1	1 major
`isomorphic-dompurify`	^3.4.0	4.2.0	1 major
`@types/node`	^25.5.2	26.2.0	1 major
`eslint-plugin-format`	^1.0.1	2.0.1	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium3

low1

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

docker/login-action@v4, depot/setup-action@v1, docker/metadata-action@v6, depot/build-push-action@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Make CI invoke the test suite it hashigh286 occurrences

.github/workflows

286 test files, no test command in the 4 workflows read

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/publish.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium

.devcontainer/Dockerfile

mcr.microsoft.com/devcontainers/python:${VARIANT}

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/auto-merge-dependencies.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.