feat: add jaspr site reusable workflow

.github/cspell.json

@@ -26,6 +26,7 @@
     "Contador",
     "endtemplate",
     "Infima",
+    "jaspr",
     "linecap",
     "localizable",
     "mostrado",

.github/dependabot.yaml

@@ -39,6 +39,19 @@ updates:
           - "minor"
           - "patch"
 
+  # Jaspr example site used to exercise the reusable workflows.
+  - package-ecosystem: "pub"
+    directory: "/examples/jaspr_site"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"
+    groups:
+      jaspr-site:
+        update-types:
+          - "minor"
+          - "patch"
+
   # Documentation site (Docusaurus).
   - package-ecosystem: "npm"
     directory: "/site"

.github/workflows/ci.yml

@@ -89,6 +89,14 @@ jobs:
       run_bloc_lint: false
       working_directory: examples/flutter_package
 
+  verify-jaspr:
+    uses: ./.github/workflows/jaspr_site.yml
+    with:
+      dart_sdk: "3.13.2"
+      jaspr_cli_version: "0.23.5"
+      setup: dart --version
+      working_directory: examples/jaspr_site
+
   verify-pana-dart:
     uses: ./.github/workflows/pana.yml
     with:
@@ -116,6 +124,7 @@ jobs:
         dart_package
         deps
         flutter_package
+        jaspr_site
         pana
         semantic_pull_request
         skills_lint
@@ -192,6 +201,7 @@ jobs:
         verify-flutter-version-file,
         verify-flutter-version-file-windows,
         verify-artifacts,
+        verify-jaspr,
         verify-pana-dart,
         verify-pana-flutter,
         verify-skills-lint,

.github/workflows/jaspr_site.yml

@@ -0,0 +1,100 @@
+name: Jaspr Site Workflow
+
+on:
+  workflow_call:
+    inputs:
+      analyze_directories:
+        required: false
+        type: string
+        default: "."
+      build:
+        required: false
+        type: boolean
+        default: true
+        description: "Whether to build the site with the Jaspr CLI."
+      build_args:
+        required: false
+        type: string
+        default: ""
+        description: "Extra arguments passed to `jaspr build` (e.g. '--no-ssr --sitemap-domain https://example.com')."
+      dart_sdk:
+        required: false
+        type: string
+        default: "stable"
+      format_directories:
+        required: false
+        type: string
+        default: "."
+      format_line_length:
+        required: false
+        type: string
+      jaspr_cli_version:
+        required: false
+        type: string
+        default: ""
+        description: "The version of jaspr_cli to activate (e.g. '0.23.5'). Empty installs the latest version."
+      runs_on:
+        required: false
+        type: string
+        default: "ubuntu-latest"
+      timeout_minutes:
+        required: false
+        type: number
+        default: 360
+        description: "Maximum minutes before GitHub cancels the job."
+      setup:
+        required: false
+        type: string
+        default: ""
+      working_directory:
+        required: false
+        type: string
+        default: "."
+    secrets:
+      ssh_key:
+        required: false
+
+jobs:
+  build:
+    defaults:
+      run:
+        working-directory: ${{inputs.working_directory}}
+
+    runs-on: ${{inputs.runs_on}}
+    timeout-minutes: ${{inputs.timeout_minutes}}
+
+    steps:
+      - name: 📚 Git Checkout
+        uses: actions/checkout@v7
+
+      - name: 🎯 Setup Dart
+        uses: dart-lang/setup-dart@v1.8.1
+        with:
+          sdk: ${{inputs.dart_sdk}}
+
+      - name: 🤫 Set SSH Key
+        env:
+          ssh_key: ${{secrets.ssh_key}}
+        if: env.ssh_key != null
+        uses: webfactory/ssh-agent@v0.10.0
+        with:
+          ssh-private-key: ${{secrets.ssh_key}}
+
+      - name: 📦 Install Dependencies
+        run: dart pub get
+
+      - name: ⚙️ Run Setup
+        if: "${{inputs.setup != ''}}"
+        run: ${{inputs.setup}}
+
+      - name: ✨ Check Formatting
+        run: dart format ${{inputs.format_line_length && format('--line-length {0}', inputs.format_line_length) || ''}} --set-exit-if-changed ${{inputs.format_directories}}
+
+      - name: 🕵️ Analyze
+        run: dart analyze --fatal-infos --fatal-warnings ${{inputs.analyze_directories}}
+
+      - name: 🏗️ Build
+        if: ${{inputs.build}}
+        run: |
+          dart pub global activate jaspr_cli ${{inputs.jaspr_cli_version}}
+          jaspr build ${{inputs.build_args}}

README.md

@@ -27,6 +27,9 @@ uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@
 # A reusable workflow for Flutter packages
 uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/flutter_package.yml@v2
 
+# A reusable workflow for Jaspr sites
+uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/jaspr_site.yml@v1
+
 # A reusable workflow for ensuring commits are semantic
 uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/semantic_pull_request.yml@v2
 

examples/jaspr_site/.gitignore

@@ -0,0 +1,30 @@
+# Files and directories created by pub.
+**/doc/api/
+.dart_tool/
+.packages
+
+# Conventional directory for build output.
+/build/
+
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/

examples/jaspr_site/README.md

@@ -0,0 +1,12 @@
+# jaspr_site
+
+[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]
+[![License: MIT][license_badge]][license_link]
+
+An example [Jaspr][jaspr_link] site used to exercise the Jaspr workflow.
+
+[jaspr_link]: https://docs.jaspr.site
+[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[license_link]: https://opensource.org/licenses/MIT
+[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg
+[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis

examples/jaspr_site/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:very_good_analysis/analysis_options.yaml

examples/jaspr_site/lib/app.dart

@@ -0,0 +1,36 @@
+import 'package:jaspr/dom.dart';
+import 'package:jaspr/jaspr.dart';
+
+/// The main component of the application.
+///
+/// By using the `@client` annotation this component is automatically compiled
+/// to JavaScript and mounted on the client.
+@client
+class App extends StatelessComponent {
+  /// Creates the main [App] component.
+  // The lint's fix rewrites this to `const new(...)`, which requires the
+  // experimental `primary-constructors` feature that `jaspr build` does not
+  // enable, so it is suppressed here.
+  // ignore: unnecessary_type_name_in_constructor
+  const App({super.key});
+
+  @override
+  Component build(BuildContext context) {
+    return const section([
+      h1([Component.text('Welcome')]),
+      p([Component.text('You successfully created a new Jaspr site.')]),
+    ]);
+  }
+
+  /// Defines the CSS styles for this component.
+  @css
+  static List<StyleRule> get styles => [
+    css('section').styles(
+      display: Display.flex,
+      height: 100.vh,
+      flexDirection: FlexDirection.column,
+      justifyContent: JustifyContent.center,
+      alignItems: AlignItems.center,
+    ),
+  ];
+}

examples/jaspr_site/lib/main.client.dart

@@ -0,0 +1,16 @@
+/// The entrypoint for the **client** environment.
+///
+/// The [main] method will only be executed on the client when loading the page.
+/// To run code on the server during pre-rendering, check `main.server.dart`.
+library;
+
+import 'package:jaspr/client.dart';
+import 'package:jaspr_site/main.client.options.dart';
+
+void main() {
+  // Initializes the client environment with the generated default options.
+  Jaspr.initializeApp(options: defaultClientOptions);
+
+  // Loads and renders all components annotated with `@client`.
+  runApp(const ClientApp());
+}

examples/jaspr_site/lib/main.client.options.dart

@@ -0,0 +1,29 @@
+// dart format off
+// ignore_for_file: type=lint
+
+// GENERATED FILE, DO NOT MODIFY
+// Generated with jaspr_builder
+
+import 'package:jaspr/client.dart';
+
+import 'package:jaspr_site/app.dart' deferred as _app;
+
+/// Default [ClientOptions] for use with your Jaspr project.
+///
+/// Use this to initialize Jaspr **before** calling [runApp].
+///
+/// Example:
+/// ```dart
+/// import 'main.client.options.dart';
+///
+/// void main() {
+///   Jaspr.initializeApp(
+///     options: defaultClientOptions,
+///   );
+///
+///   runApp(...);
+/// }
+/// ```
+ClientOptions get defaultClientOptions => ClientOptions(
+  clients: {'app': ClientLoader((p) => _app.App(), loader: _app.loadLibrary)},
+);

examples/jaspr_site/lib/main.server.dart

@@ -0,0 +1,31 @@
+/// The entrypoint for the **server** environment.
+///
+/// The [main] method will only be executed on the server during pre-rendering.
+/// To run code on the client, check the `main.client.dart` file.
+library;
+
+import 'package:jaspr/dom.dart';
+import 'package:jaspr/server.dart';
+import 'package:jaspr_site/app.dart';
+import 'package:jaspr_site/main.server.options.dart';
+
+void main() {
+  // Initializes the server environment with the generated default options.
+  Jaspr.initializeApp(options: defaultServerOptions);
+
+  // Starts the app by rendering the root document structure.
+  runApp(
+    Document(
+      title: 'jaspr_site',
+      styles: [
+        css('html, body').styles(
+          width: 100.percent,
+          minHeight: 100.vh,
+          padding: Padding.zero,
+          margin: Margin.zero,
+        ),
+      ],
+      body: const App(),
+    ),
+  );
+}

examples/jaspr_site/lib/main.server.options.dart

@@ -0,0 +1,30 @@
+// dart format off
+// ignore_for_file: type=lint
+
+// GENERATED FILE, DO NOT MODIFY
+// Generated with jaspr_builder
+
+import 'package:jaspr/server.dart';
+import 'package:jaspr_site/app.dart' as _app;
+
+/// Default [ServerOptions] for use with your Jaspr project.
+///
+/// Use this to initialize Jaspr **before** calling [runApp].
+///
+/// Example:
+/// ```dart
+/// import 'main.server.options.dart';
+///
+/// void main() {
+///   Jaspr.initializeApp(
+///     options: defaultServerOptions,
+///   );
+///
+///   runApp(...);
+/// }
+/// ```
+ServerOptions get defaultServerOptions => ServerOptions(
+  clientId: 'main.client.dart.js',
+  clients: {_app.App: ClientTarget<_app.App>('app')},
+  styles: () => [..._app.App.styles],
+);