Imported from SharezoneApp/sharezone-app (
AGENTS.md). Install upstream withnpx skills add SharezoneApp/sharezone-app. Copyright stays with the author.
Agents
Project Overview
Sharezone is a collaborative school organization app for iOS, Android, macOS and web built with Flutter.
Repository Overview
- .github/: Our automated CI/CD pipeline
- app/: The main "Sharezone" app
- lib/: A place for our internal Dart/Flutter packages. Used to modularize and share code between app, website and admin console.
- docs/: Our end user documentation https://docs.sharezone.net, built with Nextra.
- website/: Our sharezone.net website (not the web app) built with Flutter.
- console/: Our admin console used by the Sharezone team for support / administrative tasks. Also built with Flutter.
- tools/sz_repo_cli/: Our custom
szDart CLI used by developers and CI/CD pipelines. Helps with tasks like testing, analyzing, building, deploying etc.
This repository doesn't contain the backend code.
Running the app
Android, iOS & macOS
cd app
fvm flutter run --flavor dev --target lib/main_dev.dart
Web
cd app
fvm flutter run --target lib/main_dev.dart
This will use our hosted development backend.
Tests
Make sure your changes are tested. Write helpful and meaningful tests. Do not write useless tests.
Executing all tests
You execute all tests (except integration tests) with the following command:
sz test
[!NOTE] This command is relatively slow because it runs all tests across all packages. During development, you may want to only run a subset of tests to speed things up.
Executing unit & widget tests
To run all unit and widget tests, use:
sz test --exclude-goldens
You can also run tests for a specific directory or file (helpful for debugging):
# Run all unit & widget tests in the app directory
fvm flutter test app/test/
# Run a single test file
fvm flutter test app/test/grades/grades_service_test.dart
Executing golden tests
To run only golden tests, execute:
sz test --only-goldens
You can also limit golden tests to specific directories or files:
# IMPORTANT: Navigate to the directory where the test_goldens directory is located.
cd app # or ./lib/sharezone_widgets, ./lib/feedback_shared_implementation, etc.
# Run a single golden test file or directory
fvm flutter test test_goldens/grades/pages/grades_page/grades_page_test.dart
[!NOTE] Golden tests currently only work on macOS due to rendering differences across platforms. On other platforms, the golden tests will be skipped.
To generate (or update) golden files, use:
# Generate golden files for all tests:
sz test --update-goldens --only-goldens
Formatting
sz format
Internationalization (i18n / l10n)
We organize our multi-language support in the lib/sharezone_localizations package.
Adding new strings
- Add the new string to
lib/sharezone_localizations/l10n/app_de.arb. This is our default language. - Add the new string to
lib/sharezone_localizations/l10n/app_en.arb. Metadata (e.g.@your_new_string) should only be added to the German file. - Run
sz l10n generateto generate the Dart files for the new string.
Use new strings
- Add
import 'package:sharezone_localizations/sharezone_localizations.dart';to the file where you want to use the new string. - Use the new string like this:
context.l10n.your_new_string.
Do not add SharezoneLocalizations to business logic. Only use it in the UI.
Style Guide
Follow the Effective Dart style guide.
Do not use SharezoneContext for new code. This is legacy code.
For new features, we use Provider for state management. BlocProvider is legacy code.
Keep business logic out of the UI. Use Provider for state management.