--graphql (alias: --gql)

Includes GraphQL support in the scaffolded project alongside the default REST layer. The two flags are identical — --gql is a four-letter shorthand. Default is off (REST-only).

gofasta new myapp                  # REST-only (default)
gofasta new myapp --graphql        # REST + GraphQL
gofasta new myapp --gql            # same as --graphql

Without this flag, the generated project has no GraphQL files, no gqlgen dependency in go.mod, no /graphql endpoint registered in routes, and no app/graphql/ directory. Adding GraphQL after the fact is possible but not automated — pick this flag at gofasta new time if you know you want it.

What gets added

When --graphql is set, the scaffold additionally:

After scaffold, go tool gqlgen generate runs automatically to materialize app/generated.go + the model types. You can re-run it any time with make gqlgen or go tool gqlgen generate directly when you change the schema.

--graphql combines with --layout=feature: the scaffold rewrites the resolver files and gqlgen.yml into the feature shape (per-resource symbols via userpkg, autobind against app/shared/dtos + app/user) before gqlgen runs. An existing project can switch layouts later with gofasta refactor.

What it interacts with

gofasta g scaffold <Resource> --graphql

The scaffold command has its own --graphql flag with different semantics. The project-level gofasta new --graphql flag is the prerequisite: it sets up the gqlgen plumbing once. The resource-level gofasta g scaffold --graphql flag is per-resource: it tells the generator to also emit GraphQL schema fragments + resolver patches for that one resource.

# Project-level (run once, at creation):
gofasta new myapp --graphql
 
cd myapp
 
# Resource-level (run per resource that should be in GraphQL):
gofasta g scaffold Product name:string price:float --graphql
gofasta g scaffold Order  total:float status:string  # REST-only, no GraphQL

You can mix: some resources REST-only, others REST + GraphQL. The two flags are independent — g scaffold --graphql will fail with a clear error if the project wasn’t created with gofasta new --graphql (no gqlgen installed, no app/graphql/ directory to patch).

The /graphql endpoint

After gofasta new --graphql, the running server exposes (routes configurable under config.yaml → graphql:):

• POST /graphql — the GraphQL endpoint (graphql.general_route)
• GET /graphql-playground — gqlgen’s interactive Playground UI (graphql.playground_route)

Both are wired through the same authentication middleware as the REST routes — JWT bearer tokens in Authorization: Bearer <token> work for GraphQL queries too.

The resolver pattern

Resolvers are split per schema file ({name}.resolvers.go) so g scaffold --graphql can append to the right file without touching unrelated ones. The root resolver.go carries the service deps (shown here for layered layout; feature layout uses userpkg "myapp/app/user"-style aliases instead):

// app/graphql/resolvers/resolver.go
package resolvers
 
import (
    svcInterfaces "myapp/app/services/interfaces"
)
 
type Resolver struct {
    UserService    svcInterfaces.UserServiceInterface
    ProductService svcInterfaces.ProductServiceInterface // added by `g scaffold Product --graphql`
}

Wire injects the services into the resolver via app/di/providers/graphql.go.

Examples

Create a fresh GraphQL-enabled project

gofasta new myapp --graphql
cd myapp
gofasta init
gofasta dev --services db   # db in Docker, app on the host with hot reload — migrations run automatically

Then open http://localhost:8080/graphql-playground in a browser.

Combine with --driver

The two flags are orthogonal — combine freely:

gofasta new myapp --graphql --driver mysql
gofasta new myapp --gql --driver sqlite

Generate a GraphQL-aware resource

cd myapp
gofasta g scaffold Product name:string price:float --graphql
# This requires the project was created with --graphql.

This appends a Product type + productById / products queries + createProduct mutation to the schema, patches resolver.go to add ProductService, then re-runs gqlgen generate and wire.

When to skip --graphql

The flag adds ~1.5 MB of gqlgen dependency and ~10 generated files. If the project is going to be a pure REST API, skip the flag — the result is leaner and there’s no GraphQL machinery to maintain. You can always re-scaffold a fresh project with the flag and copy resources across if requirements change later.