Dart CLI generator for Flutter and Dart apps - extend your project with custom tasks, add a sidekick to your app.
Write your automation scripts in Dart - a language all your coworkers are comfortable with - while fully supporting debugging and testing without losing the simplicity of executing shell scripts.
Awesome examples
- Deployment scripts with multi-dimension build flavors
- Bump the version of your packages at once
- Generate release notes by combining merged PRs and completed JIRA issues
- Fix broken generated build_runner code while waiting for a fix to be merged
- Update GraphQL schemas
- Create init scripts for coworkers to set up their environment
Install the CLI generator sidekick. This is only required for generation, not for the execution of the CLI.
dart pub global activate sidekickInitialize project
sidekick init <path-to-repo> Follow the instructions and you just created your first sidekick CLI. You can execute your CLI right away using its entrypoint and use any of the existing tasks.
Assuming your CLI is called flg (short for flutter gallery), execute the flg shell script in the root of your repository.
$ ./flg
A sidekick CLI to equip Dart/Flutter projects with custom tasks
Usage: flg <command> [arguments]
Global options:
-h, --help Print this usage information.
Available commands:
analyze Dart analyzes the whole project
clean Cleans the project
dart Calls dart
deps Gets dependencies for all packages
format Formats all Dart files in the project
flutter Call the Flutter SDK associated with the project
sidekick Manages the sidekick CLI
Run "flg help <command>" for more information about a command.| Plugin | Description |
|---|---|
| sidekick_vault | Store project secrets encrypted in your repository |
| dockerize_sidekick_plugin | Wrap your Flutter Web App in a docker container |
| flutterw_sidekick_plugin | Pin a Flutter version to your project and share it with your team |
See the full list of available plugins
To write your own plugin checkout the docs.
To install more command, you can use install plugins with
$ <cli> sidekick plugins install <pub-package>Runs the analyzer for all packages in the project.
Runs the bundled dart runtime with any arguments.
By calling flg dart you make sure to always use the correct dart version anyone else in your project is using.
Deletes the build directory of the main application. This commands code is part of your CLI, intended to be modified to your needs.
Gets all dependencies for all packages in your project. This will become your most used command in no time!
Formats all Dart files in the project. Default is 80.
Change the line length for a specific package by adding the following to the pubspec.yaml of the package:
format:
line-length: 120Runs the bundled flutter runtime (provided via flutter-wrapper) with any arguments.
By calling flg flutter you make sure to always use the correct flutter version, like anyone else of your team.
You can execute your CLI from anywhere. To do so, run the install-global command and follow the instructions.
$ ./flg sidekick install-global
Please add $HOME/.sidekick/bin to your PATH.
Add this to your shell's config file (.zshrc, .bashrc, .bash_profile, ...)
export PATH="$PATH":"$HOME/.sidekick/bin"
Then, restart your terminalAfter adjusting your PATH, you can execute the CLI from anywhere.
$ flgA plugin template can be generated with sidekick plugins create --template <template type> --name <plugin name>.
This plugin was generated from the template $templateType.
The --template parameter must be given one of the following values:
-
install-only
This template is the very minimum, featuring just atool/install.dartfile that writes all code to be installed into the users sidekick CLI.It doesn't add a pub dependency with shared code. All code is generated in the users sidekick CLI, being fully adjustable.
-
shared-command
This template adds a pub dependency to a shared CLICommandand registers it in the user's sidekick CLI.This method is designed for cases where the command might be configurable with parameters but doesn't allow users to actually change the code.
It allows updates (via
pub upgrade) without users having to touch their code. -
shared-code
This template adds a pub dependency and writes the code of aCommandinto the user's sidekick CLI as well as registers it there.The
Commandcode is not shared, thus is highly customizable. But it uses shared code from the plugin package that is registered added as dependency. Update of the helper functions is possible via pub, but the actual command flow is up to the user.
<cli> sidekick plugins install <plugin name on pub server, e.g. sidekick_vault>By default, pub.dev is used as pub server. A custom pub server can be used with the --hosted-url
parameter.
<cli> sidekick plugins install --source git <link to git repository>Optional parameters:
--git-ref: Git branch name, tag or full commit SHA (40 characters) to be installed--git-path: Path of git package in repository (use when repository root contains multiple packages)- e.g.
${cliNameOrNull ?? 'your_custom_sidekick_cli'} sidekick plugins install --source git --git-path sidekick_vault https://github.com/phntmxyz/sidekick
- e.g.
<cli> sidekick plugins install --source path <path to plugin on local machine>The entrypoint usually automatically detects when you changed the source code of your CLI.
But for rare cases (like path dependencies) it is not possible to detect changes.
In those scenarios use flg recompile to force recompile your CLI.
Writing your own commands is done in two steps.
- Create a class for your new command, give it a
name.
import 'package:sidekick_core/sidekick_core.dart';
class YourCommand extends Command {
@override
String get description => 'does foo';
@override
String get name => 'foo';
@override
Future<void> run() async {
// your custom code here
}
}- Register your new command in the
packages/flg_sidekick/lib/flg_sidekick.dartfile by adding it to the runner
// Generated by `sidekick init`
Future<void> runFlg(List<String> args) async {
final runner = initializeSidekick(mainProjectPath: '.');
runner
..addCommand(FlutterCommand())
//.. more commands
..addCommand(InstallGlobalCommand())
..addCommand(YourCommand()); // <-- Register your own command
//...The sidekick CLI is based on package:args.
Use the existing argParser of Command to define and parse the arguments of your command.
class EchoTextCommand extends Command {
@override
String get name => 'echo-text';
@override
String get description => 'Echos the text';
EchoTextCommand() {
argParser.addOption('text');
}
@override
Future<void> run() async {
final cliName = argResults!['text'] as String?;
print('echo $cliName');
}
}$ flg echo-text --text="Hello World"
Hello WorldOnce you start automating your development workflow, you rather soon hit the limits of Bash. Not only is it hard to learn for newcomers, but also hard to understand for experienced developers. The lack of dependency management and JSON parsing are only a few reasons that rule it out as a usable scripting language.
Build systems like Gradle allow you to write your tasks. But Dart and Flutter projects are not compatible with Gradle and don't offer an easy way to add custom tasks.
While you can place your dart scripts in /tool and add dev_dependencies to your pubspec.yaml you might rather soon run into version conflicts between your app and your scripts.
Let's face it, you need a standalone dart project for your custom CLI, and sidekick does the heavy lifting for you.
The sidekick CLI is self-executable
- Executing the CLI requires no extra dependencies. The entrypoint can be executed as shell script. That makes it easy to use on CI/CD servers.
- By calling the
entrypointshell script, it automatically downloads a (pinned) Dart runtime and compiles the CLI project. - Self-executable and self-contained. Dependencies are not shared with the app.
Full control of the source code
- Changing existing code doesn't require a PR to the sidekick project. You can customize the generated commands to your liking.
- There is no program between your CLI and the Dart compiler that reads, alters, wraps or breaks your code.
- You don't like how the CLI handles errors or prints the help page? You can change that, you have full control
Being able to use all the benefits of a modern language
- Like any pure Dart program, the sidekick CLI can be executed with a debugger. No need for print statements!
- Full IDE support and syntax highlighting
- Full testing support. Who doesn't want unit tests for their custom tasks?
That's useful when you want to test the sidekick cli during development on your machine. Tests are great, but sometimes you want to see the beast in action.
cd sidekick
dart pub global activate -s path .Copyright 2021 phntm GmbH
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent