wholesome_cli 1.0.1

  • Readme
  • Changelog
  • Installing
  • 36

A Command Line Tool that facilitates code generation for Flutter projects.

Wholesome is a Command Line Tool that aims to facilitate code generation for Flutter projects, proposing a default architecture based on BLoC pattern.

Requeriments #

This tool is executed using pub and generate code for Flutter projects this means that you will need:

Installation #

Wholesome-cli now is a (pub.dev package)[https://pub.dev/packages/wholesome_cli/versions/1.0.0] and you can install the stable version from pub, or installit from this repo if you want the latest dev version.

Pub #

pub global activate wholesome_cli

Git Online #

You can install the tool from this repo link by running the following line:

pub global activate --source git https://github.com/clawstudios/wholesome-cli.git

Git Local #

If you cloned the repository, you can install the tool with the following line replacing <path> with the path where the repo is located on your computer.

pub global activate --source path <path>

Add the executable folder to $PATH #

To execute Wholesome from your command line, you need to add the pub cache folder to the PATH. Check out the Running Script section in the pub-global Dart documentation to add the path correctly for your system.

Before Starting #

This tool is based on the following folder structure. You can read more about each folder in the section of each subcommand of the generator.

/ myproject
  |- .idea
  |- android
  |- assets
  |- ios
  |- lib
    |- common
    |- components
        |- mycomponent
            |- mycomponent.bloc.dart
            |- mycomponent.events.dart
            |- mycomponent.state.dart
            |- mycomponent.view.dart
    |- guards
    |- models
    |- pages
        |- mypage
            |- mypage.bloc.dart
            |- mypage.events.dart
            |- mypage.state.dart
            |- mypage.view.dart
    |- services
  |- test

Commands #

Every Wholesome command needs to be executed by the wsm binary. At the moment, it supports the following commands and subcommands:

New #

The new command generates a new Flutter project with the provided name, the previously detailed folder folder structure, and some boilerplate code.

wsm new myproject

This command will run 'flutter new' and then will generate the structure and files.

This command also generates the following files inside the common folder:

  • assets.dart
  • colors.dart
  • helpers.dart
  • routes.dart
  • styles.dart

Assets, Colors and Styles #

These are files for storing constants with asset paths, custom colors, or custom styles that you need to reuse on every part of the app.

You can import the files in the following way:

import  'package:myproject/common/assets.dart'  as ASSETS;
import  'package:myproject/common/colors.dart'  as COLORS;
import  'package:myproject/common/styles.dart'  as STYLES;

Helpers #

This is a file created to put all the helper functions that you will use to develop your app.

You need to import it like this:

import  'package:myproject/common/helpers.dart'  as HELPERS;

And you will find two methods for printing to console.

HELPERS.printError('This is an error message.');
HELPERS.printWarn('This is a warning message.');

Routes #

In this file, you will find a ROUTES Map in where you can add routes and associate them with the generated Page constructor.

For more information about routing, please check Flutter Routing Docs.

Generate #

This command generates boilerplate code, it receives one subcommand as a parameter and you must execute this command under a Flutter Project

wsm generate <subcommand>

Component #

A component is a reusable implementation of code that could have one or more files.

Stateful Component #

For components that need state management, Wholesome generates a set of files inside a folder named the same as the component (as you can see in the Before Starting section, inside the 'components' folder)

wsm generate component <name>

Generated Files:

name.bloc.dart This file contains all the Business Logic and also is intended to manage the State of the component through events.

name.events.dart Contains an abstract class ready to be extended by custom events used to comunicate between BLoC and View.

name.state.dart Contains a class with the State data of the component and only can be modified by the BLoC.

name.view.dart: Is a StatefulWidget with a BLoC instance in it and a dispose implementation that includes the _bloc.dispose() call that is needed to shutdown the BLoC controllers when disposing the view.

Stateless Component #

For components without state management, Wholesome will generate only a StatelessWidget that will be used as a view.

wsm generate component <name> -s
# or
wsm generate component <name> -stateless

Guard #

Guard functionality is to manage the access to one or more views, that's why you will find a default canActivate method that returns a boolean ready to be used from a Page. Guards can be extended as needed. These files are created under the 'guards' folder as shown in the Before Starting section.

wsm generate guard <name>

Usage #

Guards are implemented as mixins, you can use it on a generated page adding the 'with' keyword to the state class. More info about mixins here

...
class _HomePageState extends State<HomePage> with ExampleGuard {

  HomePageBloc _bloc = HomePageBloc();

  @override
  void initState() {
      if (!this.canActivate(context)) {
          // Get out of here
      }
  }
...

Model #

Models are classes that represent different data models handled inside an app such as user data to show in a profile view. Models are located inside the 'models' folder. (check the previously detailed folder structure).

wsm generate model <name>

Page #

Pages are StatefulWidgets with the same structure as components, but they can be accessed navigating to their specific route that is also generated by this subcommand. In pages is where you will instantiate components and trigger events to the BLoC for handling state and model mutations.

Pages are located inside 'pages' folder. (check the previously detailed folder folder structure).

wsm generate page <name>

See the (Routes)[https://github.com/clawstudios/wholesome-cli/blob/master/README.md#routes] section if youe need to add a route manually.

Service #

Services are singletons that expose methods to interact with external resources such as APIs or databases.

Services are located inside the 'services' folder. (check the previously detailed folder folder structure).

wsm generate service <name>

Credits #

This tool is a development in progress by Claw Studios and is under BSD License.

If you want to help, contribute or report a bug please use the following channels

1.0.1 #

  • We are now available on pub.dev.
  • BLoC are no longer singletons.
  • 'generate component' now accepts the documented flag for Stateless. Read more here
  • Guards implementation changed from singletons to mixins.
  • 'generate pages' now adds a default route to the generated page.

1.0.0 #

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate wholesome_cli

2. Use it

The package has the following executables:


$ wsm

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  wholesome_cli: ^1.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:wholesome_cli/wholesome_cli.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
73
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
71
Overall:
Weighted score of the above. [more]
36
Learn more about scoring.

We analyzed this package on Nov 7, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.6.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:wholesome_cli/wholesome_cli.dart.

Health suggestions

Fix lib/commands/generate/subcommands/page.dart. (-8.17 points)

Analysis of lib/commands/generate/subcommands/page.dart reported 17 hints, including:

line 5 col 81: Use lowercase_with_underscores when specifying a library prefix.

line 6 col 83: Use lowercase_with_underscores when specifying a library prefix.

line 7 col 82: Use lowercase_with_underscores when specifying a library prefix.

line 8 col 81: Use lowercase_with_underscores when specifying a library prefix.

line 55 col 3: Prefer using /// for doc comments.

Fix lib/commands/new/new.dart. (-7.24 points)

Analysis of lib/commands/new/new.dart reported 15 hints, including:

line 10 col 66: Use lowercase_with_underscores when specifying a library prefix.

line 11 col 66: Use lowercase_with_underscores when specifying a library prefix.

line 12 col 67: Use lowercase_with_underscores when specifying a library prefix.

line 13 col 66: Use lowercase_with_underscores when specifying a library prefix.

line 14 col 64: Use lowercase_with_underscores when specifying a library prefix.

Fix lib/commands/generate/subcommands/component.dart. (-6.31 points)

Analysis of lib/commands/generate/subcommands/component.dart reported 13 hints, including:

line 5 col 81: Use lowercase_with_underscores when specifying a library prefix.

line 6 col 83: Use lowercase_with_underscores when specifying a library prefix.

line 7 col 82: Use lowercase_with_underscores when specifying a library prefix.

line 8 col 81: Use lowercase_with_underscores when specifying a library prefix.

line 52 col 3: Prefer using /// for doc comments.

Fix additional 17 files with analysis or formatting issues. (-8.88 points)

Additional issues in the following files:

  • lib/commands/generate/subcommands/guard.dart (6 hints)
  • lib/commands/generate/subcommands/model.dart (6 hints)
  • lib/commands/generate/subcommands/service.dart (6 hints)
  • bin/main.dart (Run dartfmt to format bin/main.dart.)
  • lib/commands/generate/generate.dart (Run dartfmt to format lib/commands/generate/generate.dart.)
  • lib/commands/generate/subcommands/files/bloc.dart (Run dartfmt to format lib/commands/generate/subcommands/files/bloc.dart.)
  • lib/commands/generate/subcommands/files/events.dart (Run dartfmt to format lib/commands/generate/subcommands/files/events.dart.)
  • lib/commands/generate/subcommands/files/guard.dart (Run dartfmt to format lib/commands/generate/subcommands/files/guard.dart.)
  • lib/commands/generate/subcommands/files/model.dart (Run dartfmt to format lib/commands/generate/subcommands/files/model.dart.)
  • lib/commands/generate/subcommands/files/service.dart (Run dartfmt to format lib/commands/generate/subcommands/files/service.dart.)
  • lib/commands/generate/subcommands/files/state.dart (Run dartfmt to format lib/commands/generate/subcommands/files/state.dart.)
  • lib/commands/generate/subcommands/files/view.dart (Run dartfmt to format lib/commands/generate/subcommands/files/view.dart.)
  • lib/commands/new/files/assets.dart (Run dartfmt to format lib/commands/new/files/assets.dart.)
  • lib/commands/new/files/colors.dart (Run dartfmt to format lib/commands/new/files/colors.dart.)
  • lib/commands/new/files/helpers.dart (Run dartfmt to format lib/commands/new/files/helpers.dart.)
  • lib/commands/new/files/main.dart (Run dartfmt to format lib/commands/new/files/main.dart.)
  • lib/commands/new/files/routes.dart (Run dartfmt to format lib/commands/new/files/routes.dart.)

Maintenance suggestions

The package description is too short. (-19 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and wholesome_cli.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.5.0 <3.0.0
args ^1.5.2 1.5.2
path ^1.6.4 1.6.4
recase ^2.0.1 2.0.1
Dev dependencies
pedantic ^1.8.0
test ^1.6.0