Creating a Client SDK

We want to support as many use-cases as possible with out client SDKs. We believe this will be one of the big differentiators between Vexilla and other feature flag tools. However, it is a lot to do ourselves. If you want to create an SDK for a language we don't support yet, this guide will help you do that.

Depending on the kind of language you are implementing for, the process will feel a bit different. Dynamic languages will likely follow the patterns in the JS/TS SDK. Strictly-typed languages will probably want to follow the patterns in the Rust SDK.

Your client should maintain lookup tables that allow consumers to use the exact ID, exact name, or publisher-normalized name alias without changing any functionality. If using the CLI to generate types, your users will likely pass ID values obfsucated behind contants or enums.

Use the shared, pinned normalization rules for lookup aliases. The normalizeName implementation reproduces the publisher's case conventions across SDK languages without depending on the host Unicode version or locale. It replaces the JS client's direct use of case for aliases; other uses, including CLI identifier generation, still need the package.

The constructor needs to take in a few arguments to set up the rest of the functionality.

  • config: This contains the main configuration values.
    • baseUrl: string: The URL where your flags live without a file path. The file path will be appended internally when fetching the manifest and flags.
    • environment: string: This corresponds to the environment you want to use to determine flag functionality. Can be the name value or environmentId value.
    • customInstanceId: an optional finite numeric or string instance ID for gradual and selective flags. Toggles and values do not require an ID. Use the language's native naming convention, such as Lua's custom_instance_id.
  • showLogs: optional boolean, disabled by default. Use the language's native naming convention, such as show_logs. Report successful and failed manifest/group fetching and installation through the native logger or standard error. Preserve the original return value or error. Do not log instance IDs, flag values, credentials, full URLs, or raw callback errors. Avoid logging every flag evaluation.

Use descriptive domain names in the implementation. Prefer groupId, environmentId, feature, and manifestSnapshot to ambiguous identifiers such as id, env, f, and s. Expand compressed branches and multiple statements into ordinary, readable control flow. A small algorithm's local loop index can stay short when its meaning is clear.

The implementation of these methods will depend on the specific language. Some languages will allow overloading and dynamic typing more than others. e.g.: In the case of Rust, there are multiple should variations to support different data types.

  • should: This is the main function consumers of your SDK will be using. It will handle Toggle, Gradual and Selective flag types. It returns a boolean value.
  • value: This method is specifically for consuming Value flag types. The return value will depend on the Value flags type. Strings, Integers, and Floats are currently supported.
  • getManifest: Fetches the manifest file. It only returns the contents.
  • setManifest: Sets a manifest in the client based on the fetched manifest values and creates the Group lookup table.
  • syncManifest: Performs both getManifest and setManifest as a convenience method.
  • getFlags: Fetches a flag group. Only returns the contents.
  • setFlags: Sets a flagGroup based on a getFlags result and creates the lookup tables for Environments and Features.
  • syncFlags: Performs both getFlags and setFlags as a convenience method.

Use the shared corpus and receipt protocol described in the contribution guide and contract/CORPUS.md. It defines literal hash, binary64 rollout, millisecond UTC schedule, validation, lifecycle, and failure expectations. Run the actual SDK paths against the producer's immutable bytes; do not copy an evaluator into the adapter or relax a vector for one language. A skipped or empty native suite cannot earn a receipt.

Validate fetched data and direct setters before replacing caches. Preserve false, zero, empty strings/lists/maps, compatible extra fields, safe integer bounds, and complete environment features. Do not coerce strings/booleans, invent seeds/dates, or let caller mutation bypass validation. Reject unpaired surrogates and invalid UTF-8 in every string and key, including compatible extras, before a decoder replaces them. Accept valid pairs and literal U+FFFD without normalization. Names use the publisher’s pinned normalization and timezone data, with stale aliases removed on refresh. Select the complete feature from the environment.

Hash UTF-8 bytes with unsigned 32-bit FNV-1a. Numeric IDs use ECMAScript binary64 text, and rollout membership uses the untruncated seeded remainder and strict <. Resolve invalid kinds and missing IDs before scheduling. Schedules use inclusive UTC integer-millisecond endpoints, including overnight and equal-endpoint daily windows; timezone labels keep UTC interpretation.

The required inventory is JS/TS, Python, Go, Rust, C#, Swift, Kotlin, PHP, Elixir, OCaml, and Lua. Dart is excluded. Lua uses require("vexilla_client"), a configuration table, snake-case manifest/group get/set/sync methods, and decoded-table fetch callbacks. Its required command must run Lua 5.5 and LuaJIT 2.1 separately, plus every additional version advertised by its rockspec. An unavailable or failing interpreter fails the command; one runtime cannot stand in for another.

Last but not least, we have a CLI tool. The main purpose of the tool for now will be to generate constants or enums so that consumers are not using "magic strings" everywhere.

If you are not proficient in TypeScript, we can help you out with that part.

You will need to edit the CLI tool in packages/cli for two specific things.

First is the template in packages/cli/src/templates.ts. It takes in data from the transform function and outputs idiomatic code in a place of the user's choosing.

Secondly, you will need to add a transform function that generates the values passed to the template. Use the language's identifier and reserved-word rules and escape every string literal. The Lua transformer returns a require-able table; its tests load generated constants under every supported runtime, use them in real evaluations, and check that existing language output remains unchanged.

When you have finished all of that, you are ready to make a Pull Request on the Vexilla repo.