{"id":21748295,"url":"https://github.com/surfstudio/surf-flutter-app-template","last_synced_at":"2025-04-13T16:34:31.604Z","repository":{"id":39585730,"uuid":"433757495","full_name":"surfstudio/surf-flutter-app-template","owner":"surfstudio","description":"Flutter Starter Template made by Surf 🏄","archived":false,"fork":false,"pushed_at":"2024-07-25T12:02:59.000Z","size":23185,"stargazers_count":165,"open_issues_count":2,"forks_count":26,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-27T07:35:46.567Z","etag":null,"topics":["flutter","flutter-starter","template"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/surfstudio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-01T09:13:02.000Z","updated_at":"2025-03-18T09:11:28.000Z","dependencies_parsed_at":"2023-11-09T11:37:24.355Z","dependency_job_id":"ddb50f18-126b-4a49-a9d9-9aa6b5e5620b","html_url":"https://github.com/surfstudio/surf-flutter-app-template","commit_stats":null,"previous_names":[],"tags_count":2,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surfstudio%2Fsurf-flutter-app-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surfstudio%2Fsurf-flutter-app-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surfstudio%2Fsurf-flutter-app-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surfstudio%2Fsurf-flutter-app-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/surfstudio","download_url":"https://codeload.github.com/surfstudio/surf-flutter-app-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248744408,"owners_count":21154863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flutter","flutter-starter","template"],"created_at":"2024-11-26T08:12:56.658Z","updated_at":"2025-04-13T16:34:31.584Z","avatar_url":"https://github.com/surfstudio.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./docs/images/cover.png\" height=\"220\" /\u003e\n\u003c/p\u003e\n\n# Overview 🐄\n\nWelcome to the Surf Flutter Team's project template – your springboard for launching new Flutter projects with ease and efficiency. Our template encapsulates years of experience and best practices in Flutter development, providing a solid foundation for your project. Here's what's included:\n\n- 🏗️ **Project Structure:** Adopt the tried-and-true structure we use across our projects, providing clarity and consistency.\n- 📚 **Basic Documentation:** Understand our project structure with the included basic documentation, making onboarding smooth and straightforward.\n- 🔄 **FVM Integration:** Enjoy seamless Flutter version management with Flutter Version Management (FVM) already integrated.\n- 🍦 **Pre-Configured Flavors:** We've set up basic flavors for your project – Production, and Development – to streamline your workflow.\n- 🎨 **App Icon \u0026 Splash Screen Setup:** Dive right in with pre-configured app icons and splash screens, enhancing the user experience from the start.\n- 🌍 **Localization Setup:** Reach a global audience with our ready-to-use localization setup.\n- 📦 **Default Libraries:** Benefit from a suite of libraries that we regularly use, included by default for your convenience.\n- 🛠️ **Essential Project Scripts:** Access important project scripts like code generation and cache cleaning, saving time and effort.\n- ✨ **Basic Features:** Our template includes essential features such as first-run checks, theme switching, configuration storage, and a debug screen.\n- 💉 **Dependency Injection Configuration:** Streamline your coding with our pre-configured Dependency Injection setup.\n- 🛠️ **Utilities:** Utilize the same handy utilities that have become a staple in our projects.\n- 🏛️ **Architectural Approaches with Elementary:** Our architectural methodologies based on the Elementary library, ensuring robust and scalable app architecture.\n\nThis template is more than just a starting point – it's a culmination of our expertise, designed to elevate your Flutter projects right from the beginning. Enjoy the ease of development with the Surf Flutter Team's touch!\n\n# Quick Start 🚀\n\n\u003e [!IMPORTANT]\n\u003e This section needs to be removed after template initialization.\n\nA project initialization template adopted at [Surf](https://surf.dev).\n\n## Template initialization\n\nDo the following to initialize a project:\n\n1. Specify the name of the application [here](#enter-app-name-here).\n2. Search for `flutter_template` and replace it with the name of your project where needed.\n3. Configure Firebase with the [guide](docs/firebase.md).\n4. Initialize `FirebaseCrashlytics` (you can find that in `TODO(init-project)`).\n5. Install a needed Flutter version with FVM using the command:\n\n    ```sh\n    fvm use \u003cflutter_version\u003e\n    ```\n\n    If FVM is not installed, check [FVM workflow](#fvm-workflow).\n6. Specify the Flutter version used in the project [here](#flutter-and-dart-fvm-versions-of-the-project).\n7. Setup labels for issues and pull requests in the repository settings according to the [list](docs/workflow_in_repository.md#list-of-labels-for-pr-and-issues).\n\n## Workflow in the template repository\n\nThe rules for branches, commits, and pull requests are the same as for a project repository workflow and explained [below](#workflow-in-a-repository).\n\n## One more thing\n\n\u003e [!IMPORTANT]\n\u003e If you find that some information or code in the template is outdated or found errors, do not be lazy and make a change request in the [template repository](https://github.com/surfstudio/surf-flutter-app-template). Thank you.\n\n# Enter App Name Here\n\n\u003e [!IMPORTANT]\n\u003e Enter the application name above and delete this alert.\n\n## Basic information\n\n\u003e [!NOTE]\n\u003e Add here basic information about the project, such as:\n\u003e\n\u003e - a couple words what the project is about\n\u003e - briefly, what technologies are used (BLoC, Riverpod, something specific, etc.)\n\u003e - link to Confluence space with all project documentation\n\n### Settings\n\nProject line length: 120 characters.\n\n### Dependencies\n\nRun this command to get up-to-date versions of dependencies:\n\n```sh\nfvm flutter pub get --enforce-lockfile\n```\n\n## Flutter Version Management (FVM)\n\n### Flutter and Dart FVM versions of the project\n\n\u003e [!IMPORTANT]\n\u003e Change Flutter and Dart versions below and delete this alert.\n\nFlutter: ***3.19.0*** / Dart SDK: ***3.3.0***\n\n### FVM workflow\n\nThe project uses [FVM](https://fvm.app/) for Flutter version management.\nInstallation and IDE configuration for working with FVM are described [here](https://fvm.app/docs/getting_started/installation/) and [here](https://fvm.app/docs/getting_started/configuration).\n\nFor installation the project version of Flutter, run the command:\n\n```sh\nfvm install\n```\n\nFor VSCode IDE you can also run the script [`fvm_vscode.sh`](scripts/fvm_vscode.sh):\n\n```sh\nsh scripts/fvm_vscode.sh\n```\n\nYou need to use `fvm flutter ...` everywhere instead of just `flutter ...` when working with the project.\n\n## Code generation\n\nBasic command for code generation:\n\n```sh\nfvm flutter pub run build_runner build --delete-conflicting-outputs\n```\n\n### Assets codegen\n\nYou can easily add assets to your project by following these steps:\n\n1. Add asset to your assets folder (make sure you specify this folder in `asset` section of your [pubspec.yaml](pubspec.yaml))\n2. Run script [`spider_build.sh`](scripts/spider_build.sh):\n\n   ```shell\n   sh scripts/spider_build.sh\n   ```\n\nSpider configuration file is located [here](spider.yaml).\n\n\u003e [!NOTE]\n\u003e Add relevant information such as:\n\u003e\n\u003e - API models and services generation (basic info about SurfGen is [here](docs/surf_gen.md))\n\u003e - generating something else that is necessary for work or project launch\n\u003e\n\u003e Delete this alert after initialization of the template.\n\n### Mason\n\nThe project uses [mason](https://pub.dev/packages/mason) to generate code based on templates.\nTo install [mason](https://pub.dev/packages/mason) you need to run the command:\n\n```sh\n# Install from pub.dev\ndart pub global activate mason_cli\n\n# Or\n\n# Install from  homebrew\nbrew tap felangel/mason\nbrew install mason\n```\n\nThe project uses 2 templates - [feature](settings/bricks/feature) and [screen](settings/bricks/screen).\nIn order for templates to be used, they need to be obtained from [mason.yaml](mason.yaml). Run the following command:\n\n```sh\nmason get\n```\n\nTo generate code based on a template, you need to run the following command:\n\n```sh\nmason make TEMPLATE_NAME # insert the template 'feature' or 'screen' instead of TEMPLATE_NAME\n```\n\n## Requirements for running the app\n\n\u003e [!NOTE]\n\u003e Add relevant information such as:\n\u003e\n\u003e - VPN settings for development\n\u003e - test/development accounts\n\u003e\n\u003e Or just put \"No\".\n\u003e Delete this alert, but don't delete this section.\n\n## Project scripts\n\nAll scripts are located in the [scripts](scripts) folder and described [here](docs/scripts.md).\n\n## Build\n\n### Versioning\n\n\u003e [!NOTE]\n\u003e Explain here a versioning system used in the project.\n\u003e\n\u003e Delete this alert after initialization of the template.\n\nFor example, you can use this approach:\n\nGiven the version number MAJOR.MINOR.PATCH, the following should be incremented:\n\n- MAJOR version, based on the last number of release year 2021 -\u003e 1, 2022 -\u003e 2, 2023 -\u003e 3, ...\n- MINOR version, month of release -\u003e 1, 2, 3 ... 12\n- PATCH version, the day on which the release is made -\u003e 1, 2, 3, ... 31\n\nBuild number or versionCode, which comes after +, is added following this rule — combine all the values of the application version and add a place for version counting.\n\n```text\n3.11.29+31129000 // first build for the date November 29, 2023\n3.11.29+31129001 // second build for the date November 29, 2023\n4.01.03+30103001 // second build for the date January 3, 2024\n```\n\n### Flavors\n\nThe project has two flavors: `dev` and `prod`. The `dev` flavor is used by default.\nThe guide to adding flavors can be found [here](docs/flavors.md).\n\nThere are cases when you need to add different functionality for `dev` and `qa` mode. For example, if you need different logging or feature-toggle options. Then you can add the `qa` mode to the `enum BuildType` and create a `main_qa.dart` file with the `main()` function in the `lib/` folder. For example:\n\n```dart\nvoid main() {\n  run(const Environment(buildType: BuildType.qa));\n}\n```\n\nThen you need to add `qa` flavor ([guide](docs/flavors.md)).\n\n### Build guides\n\n\u003e [!NOTE]\n\u003e Add here guides for building the app or skip this section.\n\u003e\n\u003e Delete this alert, but don't delete this section.\n\n### App Signature, Certs and secrets\n\nAndroid Application Signature guide can be found [here](docs/sign_app_rules_android.md).\n\niOS certs and profiles should be saved here: `ios/certs`. But don't store them in the project repository!\n\n## Problems and possible solutions\n\n\u003e [!NOTE]\n\u003e Add problems and possible solutions here as you work with the project.\n\u003e\n\u003e Delete this alert, but don't delete this section.\n\n## Workflow in a repository\n\nThe workflow includes the following:\n\n- [Branching in a repository](docs/workflow_in_repository.md#branching-in-a-repository)\n- [Commits](docs/workflow_in_repository.md#commits)\n- [Pull requests](docs/workflow_in_repository.md#pull-requests)\n- [List of labels for PR and issues](docs/workflow_in_repository.md#list-of-labels-for-pr-and-issues)\n- [Change log](docs/workflow_in_repository.md#change-log)\n- [Technical debt](docs/workflow_in_repository.md#technical-debt)\n\n## Architecture and project structure\n\nThe overview of the architecture and structure can be found here:\n\n- [Architecture](docs/architecture_and_project_structure.md#architecture)\n- [Project structure](docs/architecture_and_project_structure.md#project-structure)\n\n## Analytics\n\nEnabled:\n\n- [flutter_surf_lint_rules](https://pub.dev/packages/surf_lint_rules)\n- [dart_code_metrics](https://pub.dev/packages/dart_code_metrics)\n  to gathering project metrics; the project has already been configured.\n\n## Navigation\n\nNavigation is centered around the [AutoRoute](https://pub.dev/packages/auto_route) package.\nWe use a class called AppRouter for global navigation around an app and StackRouter for nested navigation.\n\nDespite the fact that StackRouter could be referred to directly through the context in WidgetModel, it should be passed explicitly to the WidgetModel constructor. With StackRouter used in the context, an effective navigation stack can be obtained and managed in this router. AppRouter, in turn, is stored in the AppScope dependencies and recovered from there.\n\n## DI\n\n[Provider](https://pub.dev/packages/provider) is our choice for DI.\n\nDependencies are grouped into container entities with an interface describing a set of dependencies supplied. This entity is, in turn, supplied to a functionality with a [DiScope](./lib/features/common/widgets/di_scope/di_scope.dart) widget, which is used as a wrapper for a corresponding functionality.\n\nFor example, [AppScope](./lib/features/app/di/app_scope.dart) is the base entity for the entire app. It contains dependencies that function through the entire lifecycle of the app. We wrap the whole app in the DiScope and pass a factory that returns the AppScope.\nIf a functionality needs some dependencies specific to it only, they are isolated into a separate entity, which is to be wrapped around the functionality.\n\n## Localization\n\nThe basic rules and tips for working with localization are described in [guide](docs/localization.md).\nMore information on working with localization can be found [here](https://docs.flutter.dev/accessibility-and-localization/internationalization).\n\n## Theming\n\nThe basic rules and tips for working with theming are described in the [guide](docs/theming.md).\n\n## Icons launcher\n\nThe basic rules and tips for working with icon generation are described in the [guide](docs/icons_launcher.md).\n\n## Native splash screen\n\nThe Basic guide for creating a native splash screen is [here](docs/splash.md).\n\n## Additional useful practices\n\nThere are some additional useful guides in the [docs](docs) folder:\n\n- [Shared preferences](docs/shared_preferences.md)\n- [Authorization](docs/authorization.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurfstudio%2Fsurf-flutter-app-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsurfstudio%2Fsurf-flutter-app-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurfstudio%2Fsurf-flutter-app-template/lists"}