Skip to content
sling_gqlsling_gql

Working on the repo

  • Directorysling_gql/
    • .tool-versions flutter 3.47 · nodejs 24 (asdf)
    • Directorypackages/
      • Directorysling_gql/ runtime — Accessor, Selection, Cache, SlingClient, QueryBuilder
        • …
      • Directorysling_gql_gen/ generator — introspection JSON → Dart
        • …
      • Directorysling_gql_test/ test helpers — MockGraphQLServer, pumpUntilSettled
        • …
    • Directorymock-api/ graphql-yoga server the example and its tests run against
      • …
    • Directoryexample/ iOS-only Flutter app
      • …
    • Directorywebsite/ this site (Astro + Starlight)
      • …
    • AGENTS.md conventions and design decisions, read it first

  1. Install the toolchains. Flutter and Node are pinned with asdf; run every command from inside the repo so the pins apply.

    Terminal window
    git clone https://github.com/tpucci/sling_gql && cd sling_gql
    asdf install
    dart pub global activate melos
    melos bootstrap                            # pub workspace: one `pub get` for all packages

  2. Start the mock API. Space-themed, ~180 launches, cursor and offset pagination, 400 ms of artificial latency so skeletons are visible.

    Terminal window
    cd mock-api && npm install && npm start
    # → http://localhost:4000/graphql  (GraphiQL)

  3. Run the tests.

    Terminal window
    melos run test                               # all four gates below
    melos run test:runtime                       # runtime, pure Dart + widget tests
    melos run test:gen                           # generator
    melos run test:example                       # e2e; starts the mock API itself if needed
    melos run test:website                       # docs build

    The example test asserts exact request counts after each interaction. It is the one test that catches waterfalls — keep it exact.

  4. Run the example.

    Terminal window
    cd example && flutter run -d <ios-simulator-id>

    Every request is printed to the console and listed in-app (antenna icon).

  5. Change the schema. mock-api/schema.graphql is the contract; everything else is derived from it.

    Terminal window
    cd mock-api && npm run introspect          # → example/graphql/schema.json
    cd .. && melos run generate                # example/lib/generated/schema.dart

  6. Work on the website.

    Terminal window
    cd website && npm install && npm run dev   # http://localhost:4321/sling_gql/

    It deploys to GitHub Pages on every push to main that touches website/.

  7. CI and releases. Every push and pull request runs the four gates above (.github/workflows/ci.yml), plus analyze, format and a check that the example’s generated file is up to date.

    Commits follow Conventional Commits scoped by package (feat(sling_gql): …, fix(sling_gql_gen): …, docs(website): …), because releases are cut by melos from them:

    Terminal window
    melos run publish:dry-run   # pub.dev validation
    melos version               # bump + CHANGELOG + commit + `<pkg>-vX.Y.Z` tags
    git push --follow-tags      # publish.yml publishes each tagged package to pub.dev

Conventions

Section titled “Conventions”
  • Runtime stays dependency-light: package:http only. No gql, no ferry, no build_runner.
  • Every runtime behaviour change ships with a test in packages/sling_gql/test, using MockClient from package:http/testing.dart rather than the network.
  • The hand-written accessor classes at the top of packages/sling_gql/test/core_test.dart are the contract the generator must produce. Change both together.
  • example/lib/generated/schema.dart is committed and never edited by hand.
  • In example widgets, read every field you will need at the top of build(), into locals.