api-client

Whether an app has a publishable client, what it is called, where it goes and which flavor it carries are the app owner's decisions. They live in app.config.ts under publicApi.client, and voltro api-client is how they are read, changed and acted on without editing the file by hand. The client itself is described on the TypeScript client page.

#The decision

// app.config.ts
export default defineApi({
  publicApi: {
    profile: 'standard',
    artifacts: ['openapi', 'typescript'],   // voltro dev keeps the package written
    client: {
      package: '@acme/api-client',          // default @app/api-client
      out: 'sdk/ts',                        // default sdk/typescript, relative to the app
      flavor: 'both',                       // plain | effect | both
      license: 'MIT',
      packageVersion: '1.0.0',
      // apiVersion: 'v2', baseUrl: 'https://api.example.com'
    },
  },
})

Field	Meaning
package	The npm name.
out	Where the package is written, relative to the app root.
flavor	plain — the Promise client, no Effect anywhere; effect — the Effect service; both — . plain and ./effect Effect, with effect an optional peer.
license	The license field of the generated package. Without one npm warns at publish.
packageVersion, apiVersion, baseUrl	The package's version; one API version only; the client's default base URL.
artifacts: ['typescript']	voltro dev writes the package on every boot beside rpcGroup.generated.ts, touching only files whose content changed. Without it the package is written on demand.

#The command

voltro api-client show                                                   # the decision, defaults filled in
voltro api-client set --name @acme/api-client --flavor plain --license MIT
voltro api-client set --flavor both --artifact on                        # switch flavors, let voltro dev keep it written
voltro api-client set --artifact off                                     # on demand only
voltro api-client build                                                  # generate now, from the decision
voltro api-client build --flavor effect --out ./tmp/effect-only          # one run with other values; the file is unchanged
voltro api-client show --json

Flag	On
--name <pkg>, --out <dir>, --flavor plain|effect|both, --license <SPDX>, --package-version <v>, --base-url <url>, --api-version <v2>	set writes the field; build overrides it for this run; show shows the effect.
--artifact on|off	set adds or removes 'typescript' in publicApi.artifacts.
--json	Machine-readable output.
[path]	The app root. Default: the current directory.

set edits publicApi.client (and artifacts) through the TypeScript AST, so a hand-written config keeps its comments and its shape; it follows export default config to its declaration and refuses a publicApi that is not an object literal, naming the file. build is voltro build api --target typescript started from the decision — the two share one generator.

#After a build

cd sdk/ts
pnpm install
pnpm build                    # dist/: ESM + CJS + .d.ts
pnpm publish --access public  # or your registry

The package is standalone — nothing in it reaches into the app — and the api-public template shows the whole loop.