Function Library
Studio 2 editor only. This extension type works only on sites built in the Studio 2 editor. It does not run on Harmony, the classic Wix Editor or Wix Studio (Editor X), so do not offer it for those sites. Apps can't use it: if
wix.config.jsonhas"projectType": "App", tell the user before building.
A function library bundles reusable functions the Wix editor and runtime can call — formatters, math helpers, data transformers, event handlers. It is a registered extensions.functionLibrary() extension, not a plain utility module: functions in utils.ts, helpers.ts or src/lib/ are invisible to the editor.
You MUST read FUNCTION_LIBRARY_SPEC.md before implementing a function library. It holds the manifest fields, DOM event types and type constraints; the data types are in DATA_TYPES.md.
Quick Start Checklist
Scaffold with the Wix CLI, from the project root:
npx wix generate --params '{"extensionType":"FUNCTION_LIBRARY","name":"<library-name>"}'nameis kebab-case (e.g.car-formatting) — the CLI rejects spaces and uppercase. It derives the folder,type,idand thesrc/extensions.tsregistration from it, and createssrc/extensions/site/function-libraries/{library-name}/{library-name}.ts(aformatPricestub) and{library-name}.extension.ts.In
{library-name}.extension.ts, addresources.moduleSpecifier(the scaffold omits it, see Hard Constraints) and setnameto a Title Case display name (e.g.Car Formatting, max 100 chars) — the scaffold writes the kebab-case name there, and the editor lists the library under itInstall
@wix/editor-react-typesas a devDependency if not already presentReplace the
formatPricestub in{library-name}.tswith your named exports, and theformatPriceentry in thefunctionsmap with one entry per function (parameters, return type, async flag). Keep the CLI-generatedid
moduleSpecifier sits directly under resources, next to client, not inside it. tsc does not catch a misplaced one:
resources: {
client: { /* generated, leave as is */ },
moduleSpecifier: '@/car-formatting',
},extensions comes from @wix/astro/builders/experimental (current scaffold) or @wix/custom-extensions (older scaffolds). Both work: keep the import the scaffold wrote. If tsc reports that functionLibrary does not exist on extensions, upgrade that package.
Hard Constraints
- Always set
resources.moduleSpecifierto<moduleSpecifierPrefix><library-name>(e.g.@/car-formatting).<moduleSpecifierPrefix>is@/by default, or the prefix the user gives you. Module specifiers are unique across all of Wix, not per app: an unprefixed name may already belong to another app, and the checkpoint then fails withError during component specifier upsert - Never change the
moduleSpecifierof a library that already exists — a registered module specifier cannot be renamed. The prefix rule applies to new libraries only - Exported function names MUST exactly match the keys in the
functionsmap — a mismatch means the editor references a function that doesn't exist at runtime. Named exports only, noexport default - The boolean type is
booleanValue— NOTboolean, which is a TypeScript primitive and not a validdataType - Match each declared data type to its runtime value.
richTextrequires aRichTextobject from@wix/editor-react-typeswithtext,html, andlinkList; an HTML string is not one. For plain strings, declaretext. See RichText values - Do NOT use disallowed data types (listed in the spec), at most 10 parameters per function, each parameter has exactly one of
dataTypeordomEvent, and optional parameters come last - Do NOT invent or assume new types, modules, or imports
- NEVER use mocks, placeholders, or TODOs — implement complete, production-ready functionality
Library Implementation Pattern
import type { Text, NumberType, WebUrl } from '@wix/editor-react-types';
export function capitalize(text: Text): Text {
return text.charAt(0).toUpperCase() + text.slice(1).toLowerCase();
}
export function sum(numbers: NumberType[]): NumberType {
return numbers.reduce((acc, num) => acc + num, 0);
}
export async function fetchData(url: WebUrl): Promise<Text> {
const response = await fetch(url);
return await response.text();
}
export function logEvent(eventName: Text): void {
console.log(`[event] ${eventName}`);
}Key Rules for Library Files
- Use types from
@wix/editor-react-types—Text,NumberType,BooleanValue,WebUrl, etc. — these match the runtime format Wix provides. Other types are exported under their PascalCase name too (LocalDate,TextEnum,RichText); grep the package rather than guessing. AtextEnumparameter is typedTextEnum(astring) - DOM event parameters (
domEvent) take the matching DOM type:POINTER→PointerEvent,KEYBOARD→KeyboardEvent,FOCUS→FocusEvent,CHANGE→Event,SUBMIT→SubmitEvent - Functions can be async — mark with
asyncand return aPromise<T>when the registration setsasync: true.returnsdescribes the resolved value's type, not the Promise - Void functions — functions with no return value should return
void; omitreturnsin the registration - No side-effect imports at module scope — keep the file SSR-safe
Function Definitions
Each key of the functions map is a function name and each value a Function object — see FUNCTION_LIBRARY_SPEC.md for its fields and PARAMETER_PATTERNS.md for parameter examples (optional, complex objects, arrays, textEnum, async, void, DOM events).
Reference Documentation
- Function Library Specification — Complete manifest structure, all types, and constraints
- Code Quality — requirements for every generated file
- Data Types — Disallowed and available data types, and
richTextvalues - Parameter Patterns — All parameter type examples (optional, complex objects, arrays, textEnum, async, void, DOM events)
- Complete Examples — Full function library examples with registration and implementation
- Troubleshooting — Common issues and solutions