Skip to content

Custom service configuration

A custom configuration relates to your business logic and your requirements. It is not used by PURISTA itself. The custom service config will be available in all commands and subscriptions of this service via this.config. Custom service configurations are one option to pass configuration values to commands and subscriptions. But, you can also use stores.

Service configuration and stores addressing different data. Here is a table, that will help you to understand the differences.

custom configConfig StoreSecret store
provided/managed byinfrastructure & deploymentdatabase or vendor solutionvendor solution
addressestechnical configurationbusiness configurationsecrets & confidential data
valueis set once, during instance creationfetched per usagefetched per usage
change effectsinstance restart/next deploymenton next usageon next usage
value typeobject (nested)object, string, number, boolean (key-value)string (key-value)
can be set ()*🛑 no✅ yes✅ yes
can be deleted ()*🛑 no✅ yes✅ yes
use for confidential data🙏🏻 please no, technically possible🙏🏻 please no, technically possible✅ yes
use casesthird-party url, ports, timeout settingsfeature flag, business data like currency exchange valuespasswords, auth tokens, certificates

(*) by commands and subscriptions

For a custom configuration, you must define a zod schema. Example:

export const userServiceV1ConfigSchema = z.object({
  myOption: z.string().optional()

export type UserServiceV1Config = z.input<typeof userServiceV1ConfigSchema>

As you can see, in the example a string option entry myOption is added. This field is marked as optional. Because of this, in the generated type UserServiceV1Config, the myOption is also optional.

Now, in the builder file userV1ServiceBuilder.ts in the same directory, typescript will complain on .setDefaultConfig({}). Setting the default configuration, requires to set all root fields of the default configuration. The optional flag, only relates to the input, when you create a service instance and provide a service configuration.


PURISTA follows the pattern, to always have default values, which can be overwritten, but only when there is a actual need for it.

Because of this, you need to change it in the builder file userV1ServiceBuilder.ts.

export const userV1ServiceBuilder = new ServiceBuilder(userServiceInfo)
    myOption: 'something'

Be aware

PURISTA does not deep merge configurations! If you have nested configurations, you should be aware of.