Skip to content

feat: jaspr_cli "new component" command - #838

Open
zeykafx wants to merge 26 commits into
schultek:mainfrom
zeykafx:new-component-cli
Open

zeykafx wants to merge 26 commits into
schultek:mainfrom
zeykafx:new-component-cli

Conversation

@zeykafx

@zeykafx zeykafx commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

Description

This PR implements the jaspr new command as proposed in #736.

The command can generate stateless, stateful, async, inherited or Flutter embedded view components from a mason brick (There is one brick per component type), but also jaspr_content pages:

New component creation examples:

jaspr new component ContactInfo          # stateless by default
jaspr new component TodoList --stateful
jaspr new component LoadedData --async
jaspr new component Header --with-test   # also generates test/components/header_test.dart
jaspr new component AppTheme --inherited # creates an InheritedComponent under lib/

# Embeds a flutter widget, and sets the project up for flutter embedding
jaspr new component CounterView --flutter --flutter-app-name CounterWidget --with-flutter-widget

# Dry run: preview changes without touching the disk
jaspr new component CounterView --flutter --dry-run

Options:

  • --path (-p): where the component is created, defaults to ./lib/components (or ./lib for inherited components)
    • Note that if the command is ran from somewhere outside of the project root then the component will be created in the current working directory.
    • For example, if the command is ran from "lib/components/blog", then the component is created there. If a path is provided, the component will be created under this path, e.g., running "jaspr new component ContactSheet --path contact" from "lib/components/blog" will create the component under "lib/component/blog/contact"
  • --stateless / --stateful / --async / --inherited / --flutter: component type, one allowed, defaults to stateless
  • --client: makes it a client component (ignored with a warning for async and inherited components)
  • --with-styles: adds a css styles getter (ignored with a warning for inherited components)
  • --with-test: generates a default test for the newly generated component, see below (not supported yet for inherited and flutter components, it is ignored with a warning)
  • --dry-run: prints what would be generated without generating the files
  • --flutter-app-name (or --app-name, and others): name of the Flutter widget to embed, only used with --flutter. If it is not given, the command prompts for it (defaults to MyFlutterApp).
  • --with-sample-flutter-widget (or --with-flutter-widget, ...): also generates a sample Flutter widget with the name of the flutter app, only used with --flutter. The flag is negatable, and if it is not passed at all then the command prompts for it.

The component name can be given in PascalCase, camelCase or snake_case (the name will be converted by mason). The name is also checked to be a valid dart identifier after being converted.

NOTE: --with-test will create a new test file under the "test" directory, the file location mirrors the component's location in lib/ but in test/. E.g., Creating a componentlib/components/blog/about_us.dart will create a test at test/components/blog/about_us_test.dart.
The test uses testComponents from jaspr_test (or testServer for AsyncStatelessComponent) and imports the component via using package:xyz/....
If jaspr_test is not found in the dev dependencies, then the command prompts the user to add it.

Inherited components

--inherited generates an InheritedComponent instead of a regular component. The generated class has a sample data field with a TODO to indicate the user to replace the field, an of and a maybeOf static method, and an updateShouldNotify

Example:

jaspr new component AppTheme --inherited  # creates lib/app_theme.dart

NOTE: inherited components are created under lib/ and not lib/components/, since they are not really component that will be rendered
Other note: --client, --with-styles and --with-test are ignored with a warning for these

Flutter embedded view

Adding a FlutterEmbedView to a project requires multiple steps to be done (by hand today), but the command does the following:

  • If no Flutter app name was passed with the --flutter-app-name option, then it prompts the user for one
  • prompts to add flutter and jaspr_flutter_embed to the dependencies, and flutter_lints and flutter_test to the dev dependencies, only if they are missing
  • sets flutter: embedded in the jaspr block of the pubspec file (if the flutter mode is already set to plugins, it prompts the user if they want to overwrite it or not)
  • sets uses-material-design: true in the flutter block of the pubspec
  • creates web/flutter_bootstrap.js
  • includes a ref to that script where it belongs for the current rendering mode: in the head of the Document found in lib/main.server.dart for server and static, or in web/index.html for client. If the mode cannot be read, it warns the user and gives info on how to include it manually.
  • generates a FlutterEmbedView.deferred component, with the @Import.onWeb ref to the widget and the ViewConstraints
  • If the user passed --with-sample-flutter-app, it generates a sample Flutter widget under lib/widgets/, otherwise it prompts the user if they want a sample widget

Examples:

# prompts for the widget name and for the sample widget
jaspr new component CounterView --flutter

# no prompts
jaspr new component CounterView --flutter --app-name CounterWidget --with-flutter-widget
jaspr new component CounterView --flutter --app-name CounterWidget --no-with-flutter-widget

NOTE: the generated component is very similar to what jaspr create produces when flutter embedding is selected
NOTE: --dry-run is quite useful here since this command modifies quite a few things: it lists every change (deps, pubspec blocks, bootstrap script, script ref, generated files) without writing anything.

The command behaves in a similar manner to angular's ng generate component [name] [options] command.

Content pages

jaspr new page <name> generates a new jaspr_content page from a mason brick, with the frontmatter filled in from the options.

Examples:

jaspr new page getting_started            # creates content/getting_started.md
jaspr new page guides/deploying           # nested, creates content/guides/deploying.md
jaspr new page guides --index             # creates content/guides/index.md
jaspr new page changelog --format html    # creates content/changelog.html
jaspr new page about --no-frontmatter     # no frontmatter block at all

Options: --path (-p), --format (defaults to md), --layout, --title (defaults to the name in Title Case), --description, and the flags --dry-run, --index, --sitemap, --sitemap-exclude, --meta and --frontmatter (can be negated, it is on by default).

The command also reads the ContentApp of the server entrypoint to check a few things:

  • it reads the directory argument, so that the page is created in the right place when it is not content (i.e., if the user has changed the content directory and has not provided a path for the new page, the command will place it in the custom directory instead of content/)
  • it checks parsers to prompt the user when the requested format might not be parsable (e.g., --format html while only MarkdownParser() is registered. Note that if the user wants another format than mdx/md/html this is ignored, of if the user has a custom parser we also ignore this warning)
  • Like for the parsers, it checks layouts to prompt the user when the requested --layout may not be registered

NOTE: since jaspr_content can't run as a client side application, the command errors out for client projects. It also prompts to add jaspr_content to the dependencies when it is missing.

VSCode extension support

The VSCode extension was updated to make use of the new CLI command to allow users to create new components or pages very easily.
The command is reachable from the command palette with "Jaspr: New component or page" and is split in two parts:

  1. New components:
  • Component type: the user can pick from a list of pre-made component types (e.g., Stateless component, Stateful,...). A "more" option is present, and allows the user to pick from a list of more component types (e.g., "Stateful client components with tests",...)
  • Component location: The command provides 3 options: lib/components, `lib, or another directory (which the user browses to pick)
  • Component name: The name must be a valid dart identifier (the extension checks to avoid having the CLI throw the error)
  1. New pages:
  • Page type: As for components, a list of premade page types can be selected (e.g., "Plain markdown page", "HTML blog", "Markdown docs",...). There is a custom option at the bottom which is described later
  • Page file name.
  • Page location: similar to components, provides 3 choices contents, lib, or another directory
  • For custom pages only:
    • Page format: lets the user pick one from MD/MDX/HTML/custom
    • Page layout: lets the user pick one from Blog/Docs/Empty/custom
    • Page options: Multi select picker where the user can select multiple options from index, meta, frontmatter, sitemap, sitemap-exclude (the extension warns the user (and exits) if they pick both sitemap and sitemap-exclude at the same time).
    • Optional title and description: can be skipped, the title defaults to the page name but in title case.

Type of Change

  • ✨ New feature or improvement

Ready Checklist

  • I've read the Contribution Guide.
  • In case this PR changes one of the core packages, I've modified the respective CHANGELOG.md file using
    the semantic_changelog format.
  • I updated/added relevant documentation (doc comments with ///).
  • I added myself to the AUTHORS file (optional, if you want to).

@github-actions

github-actions Bot commented Jul 23, 2026 •

Copy link
Copy Markdown

Package Version Report

The following packages have been updated:
jaspr_test : 0.24.0-beta.0 -> 0.24.0-beta.1
jaspr : 0.24.0-beta.0 -> 0.24.0-beta.1
jaspr_cli : 0.24.0-beta.0 -> 0.24.0-beta.1
jaspr_builder : 0.24.0-beta.0 -> 0.24.0-beta.1
jaspr_router : 0.10.0-beta.0 -> 0.10.0-beta.1

@zeykafx

zeykafx commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

@schultek This is still a WIP, but I'd love some feedback on this. Do you think it could be used to generate the skills too? Do you think there are more things that it should generate? Should new be changed to generate (to be more similar to angular's command)?

Thanks!!

@codecov

codecov Bot commented Jul 26, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 6.26632% with 359 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.24%. Comparing base (36fb069) to head (a2c99bb).

Files with missing lines Patch % Lines
...ckages/jaspr_cli/lib/src/commands/new_command.dart 11.44% 178 Missing ⚠️
...spr_cli/lib/src/helpers/flutter_embed_helpers.dart 0.00% 102 Missing ⚠️
...ges/jaspr_cli/lib/src/helpers/pubspec_helpers.dart 0.00% 37 Missing ⚠️
...ew_async_component/new_async_component_bundle.dart 0.00% 6 Missing ⚠️
...omponent_test/new_async_component_test_bundle.dart 0.00% 6 Missing ⚠️
.../new_component_test/new_component_test_bundle.dart 0.00% 6 Missing ⚠️
...mbedded_view/new_flutter_embedded_view_bundle.dart 0.00% 6 Missing ⚠️
...utter_widget/new_sample_flutter_widget_bundle.dart 0.00% 6 Missing ⚠️
...teful_component/new_stateful_component_bundle.dart 0.00% 6 Missing ⚠️
...less_component/new_stateless_component_bundle.dart 0.00% 6 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #838      +/-   ##
==========================================
- Coverage   69.21%   67.24%   -1.97%     
==========================================
  Files         212      222      +10     
  Lines       11926    12309     +383     
==========================================
+ Hits         8254     8277      +23     
- Misses       3672     4032     +360     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@schultek

Copy link
Copy Markdown
Owner

Looking forward to this.

Do you think it could be used to generate the skills too?

I prefer to keep the current install-skills command and keep this separate for now.

@zeykafx
zeykafx marked this pull request as ready for review August 2, 2026 16:09
@zeykafx
zeykafx requested a review from schultek as a code owner August 2, 2026 16:09
@zeykafx

zeykafx commented Aug 6, 2026

Copy link
Copy Markdown
Contributor Author

@schultek would it be better to try to integrate this directly into the next branch?

@zeykafx

zeykafx commented Aug 9, 2026 •

Copy link
Copy Markdown
Contributor Author

The VSCode extension now supports the new component and new page commands. I based the code very largely on the create extension code. I updated the description above to include more information.

The extension currently doesn't prompt the user if they want to add missing dependencies and instead raises a flag to tell the CLI to add them directly, I was debating just warning the user that they must include the missing deps themselves but that didn't seem like it would be the outcome expected by a user.

@zeykafx

zeykafx commented Aug 15, 2026

Copy link
Copy Markdown
Contributor Author

@schultek This PR is quite large, would you prefer if I split it in three parts?
1 for the new components command, then 1 for new pages, and 1 for the VSCode extension support. I could also target the next branch (because this doesn't use analyzer version 13 yet).
Let me know what you prefer

@schultek

Copy link
Copy Markdown
Owner

No need to split this up. But targeting the next branch would be great.

Also fyi I probably won't get around to properly reviewing this for a few weeks due to vacation.

@zeykafx
zeykafx changed the base branch from main to next August 21, 2026 06:38
@zeykafx

zeykafx commented Aug 25, 2026

Copy link
Copy Markdown
Contributor Author

The CI formatting check fails due to duplicate "analyzer" keys in packages/jaspr/analysis_options.yaml, this is fixed in #872. Other than that, this pr is now up to date with next

@schultek
schultek changed the base branch from next to main November 12, 2026 13:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants