Skip to main content

Interface: ReplicacheOptions<MD>

The options passed to Replicache.

Type parameters​

NameType
MDextends MutatorDefs

Properties​

auth​

• Optional auth: string

This is the authorization token used when doing a pull and push.

experimentalCreateKVStore​

• Optional experimentalCreateKVStore: ExperimentalCreateKVStore

Allows providing a custom implementation of the underlying storage layer.

This option is experimental and might be removed or changed in the future without following semver versioning. Please be cautious.

indexes​

• Optional Readonly indexes: IndexDefinitions

Defines the indexes, if any, to use on the data.

licenseKey​

• licenseKey: string

The license key for Replicache. This parameter is required for Replicache to function. See https://replicache.dev for how to acquire a license key.

YOU SHOULD PASS TEST_LICENSE_KEY IN AUTOMATED TESTS. It disables license checks for several minutes. If you pass a normal license key in tests, each test that instantiates Replicache will attempt to perform a license check against Replicache's licensing server, potentially increasing your monthly active browser profile count, slowing the test down, and spamming Replicache's servers.

logLevel​

• Optional logLevel: LogLevel

Determines how much logging to do. When this is set to 'debug', Replicache will also log 'info' and 'error' messages. When set to 'info' we log 'info' and 'error' but not 'debug'. When set to 'error' we only log 'error' messages. Default is 'info'.

logSinks​

• Optional logSinks: LogSink[]

Enables custom handling of logs.

By default logs are logged to the console. If you would like logs to be sent elsewhere (e.g. to a cloud logging service like DataDog) you can provide an array of LogSinks. Logs at or above logLevel are sent to each of these LogSinks. If you would still like logs to go to the console, include consoleLogSink in the array.

logSinks: [consoleLogSink, myCloudLogSink],

mutators​

• Optional mutators: MD

An object used as a map to define the mutators. These gets registered at startup of Replicache.

Mutators are used to make changes to the data.

Example​

The registered mutations are reflected on the mutate property of the Replicache instance.

const rep = new Replicache({
  name: 'user-id',
  mutators: {
    async createTodo(tx: WriteTransaction, args: JSONValue) {
      const key = `/todo/${args.id}`;
      if (await tx.has(key)) {
        throw new Error('Todo already exists');
      }
      await tx.set(key, args);
    },
    async deleteTodo(tx: WriteTransaction, id: number) {
      ...
    },
  },
});

This will create the function to later use:

await rep.mutate.createTodo({
  id: 1234,
  title: 'Make things work offline',
  complete: true,
});

Replays​

Mutators run once when they are initially invoked, but they might also be replayed multiple times during sync. As such mutators should not modify application state directly. Also, it is important that the set of registered mutator names only grows over time. If Replicache syncs and needed mutator is not registered, it will substitute a no-op mutator, but this might be a poor user experience.

Server application​

During push, a description of each mutation is sent to the server's push endpoint where it is applied. Once the mutation has been applied successfully, as indicated by the client view's lastMutationId field, the local version of the mutation is removed. See the design doc for additional details on the sync protocol.

Transactionality​

Mutators are atomic: all their changes are applied together, or none are. Throwing an exception aborts the transaction. Otherwise, it is committed. As with query and subscribe all reads will see a consistent view of the cache while they run.

name​

• name: string

The name of the Replicache database.

It is important to use user specific names so that if there are multiple tabs open for different distinct users their data is kept separate.

For efficiency and performance, a new Replicache instance will initialize its state from the persisted state of an existing Replicache instance with the same name, domain and browser profile.

Mutations from one Replicache instance may be pushed using the auth, pushURL, pullURL, pusher, and puller of another Replicache instance with the same name, domain and browser profile.

You can use multiple Replicache instances for the same user as long as the names are unique. e.g. name: $userID:$roomID`

pullInterval​

• Optional pullInterval: null | number

The duration between each pull in milliseconds. Set this to null to prevent pulling in the background. Defaults to 60 seconds.

pullURL​

• Optional pullURL: string

This is the URL to the server endpoint dealing with pull. See Pull Endpoint Reference for more details.

If not provided, pull requests will not be made unless a custom puller is provided.

puller​

• Optional puller: Puller

Allows passing in a custom implementation of a Puller function. This function is called when doing a pull and it is responsible for communicating with the server.

Normally, this is just a POST to a URL with a JSON body but you can provide your own function if you need to do things differently.

pushDelay​

• Optional pushDelay: number

The delay between when a change is made to Replicache and when Replicache attempts to push that change.

pushURL​

• Optional pushURL: string

This is the URL to the server endpoint dealing with the push updates. See Push Endpoint Reference for more details.

If not provided, push requests will not be made unless a custom pusher is provided.

pusher​

• Optional pusher: Pusher

Allows passing in a custom implementation of a Pusher function. This function is called when doing a push and it is responsible for communicating with the server.

Normally, this is just a POST to a URL with a JSON body but you can provide your own function if you need to do things differently.

requestOptions​

• Optional requestOptions: RequestOptions

Options to use when doing pull and push requests.

schemaVersion​

• Optional schemaVersion: string

The schema version of the data understood by this application. This enables versioning of mutators (in the push direction) and the client view (in the pull direction).