Quality and migration

Frequently asked questions

The questions that come up most often, with the short answer. Error symptoms have a page of their own in common problems.

General

Does Voodoo.js need a build step?

No. You download one file, point a <script> tag at it and write HTML. There is no compiler, no bundler and no configuration file in the way.

Which file do I pick?

Start with voodoo.min.js: it brings reactivity, directives, components, HTTP, forms, validation, masks, interface, drag and drop, notifications, dialogs, sound and storage. Switch to voodoo.full.min.js the day you need charts, spring animation, the router, languages, the inspector or the 29 built-in components. And voodoo.core.min.js exists for pages that only need state, rendering, events and requests.

Why does interpolation use a single brace?

Because it is what most people try to write first. { name } is the standard form; {{ name }} also works, for people coming from Vue and for text that needs literal braces around it.

Where did my v-* attributes go?

They are removed from the HTML once they have been processed, on purpose, to keep the DOM clean in the inspector. The behaviour keeps working because the values are held in the runtime. To keep them, V.config.cleanAttributes = false, or data-keep-attributes on the script tag.

My CSS stopped working

It probably relied on an attribute selector, like [v-tab] { ... }. Use classes: the interface directives already apply theirs , v-tab, v-active, v-drawer-panel, v-dropzone and so on.

Does it work with a restrictive Content Security Policy?

Yes, without unsafe-eval. Only style-src needs 'unsafe-inline', because of the injected CSS, and that can be dropped with data-no-styles. The security page has the ready-made policies.

Which browsers are supported?

The builds target es2018 and use Proxy, fetch, IntersectionObserver, MutationObserver and AbortController. In practice, any browser updated in the last few years. There is no Internet Explorer support, and there will not be.

Does it work in Node?

The pure modules do: reactivity, HTTP, the utilities and the parser never touch the DOM. What depends on the DOM only runs in the browser. There is no server-side rendering.

Does the library have dependencies?

None at runtime. In development there are tsup, typescript, vitest, jsdom and prettier.

Day-to-day use

How do I do something as soon as the page loads?

<div v-data="{ data: null }" v-init="load()"></div>

Or V.ready(fn) in JavaScript, or the voodoo:ready event.

How do I access an element?

<input v-ref="search">
<button @click="$refs.search.focus()">Focus</button>

Inside handlers, $el is the element that declared the directive.

How do I know whether a request is in progress?

With v-resource, it is resource.loading. In forms, it is $form.loading. On the verb directives, use v-loading="#spinner" and v-disable-loading.

Do elements created by JavaScript get directives?

Yes. A MutationObserver initialises whatever appears in the DOM after load. If you turned that off with data-no-observer, call V.walk(element) by hand.

How do I write a function with several lines inside an attribute?

Do not. The parser accepts expressions, not blocks. Put the logic in a method on v-data, on a component or on the root scope, and call it by name.

How do I debounce with a delay other than the default?

<input v-model.debounce="search" v-debounce="600">

V.data({ search: V.debounce((t) => load(t), 600) });

How do I send the mask's clean value to the server?

<input v-mask.unmask="cpf" v-model="form.cpf" v-cpf>

The screen shows 123.456.789-01 and the state holds 12345678901.

How do I validate on the server and show the error on the right field?

Return 422 with { "errors": { "email": "Already registered" } }. v-submit hands the messages out to the fields by name, and the ones with no matching field show up in a summary at the top.

Does v-sortable reorder my array?

No. It moves the elements in the DOM. Listen for voodoo:sorted and reorder the array, or save the order on the server, without that, the next render goes back to the old order.

Can I use it together with a CSS framework or my own CSS?

Yes. Voodoo does not impose a style. The interface directives inject only the minimum, and you can turn that off with data-no-styles. With a utility CSS framework, point the theme colours at the --v-* variables and the two start moving together.

Can I use it together with jQuery, Alpine or Vue?

Yes, they all use the standard DOM. Mark the other library's region with v-ignore so that Voodoo does not touch it.

How do I write tests?

The core works in jsdom. The project's pattern is to mount a snippet, walk it and check:

document.body.innerHTML = '<div v-data="{ n: 0 }"><b v-text="n"></b></div>';
V.start();
await V.nextTick();
expect(document.querySelector('b').textContent).toBe('0');

V.flushSync() applies everything pending without waiting for the microtask.

Common errors

Symptom	Most likely cause
Nothing happens, the HTML shows up raw	The file did not load, or `data-manual` without `V.start()`
The content flashes before it renders	The `[v-cloak]` rule is missing
`Maximum call stack`	An effect writes to the same key it reads
`v-for` loses focus on the field	`:key` is missing
The component cannot see the surrounding `v-data`	That is the default. Use props, or `inheritScope: true`
The confirmation appears twice	`v-confirm` on the same element as an HTTP verb
The translation disappears when the language changes	`v-t-params` is read only once; use `$t`
The chart goes back to being a line chart	The `v-chart-*` attributes are read at mount

Each of these, with the full workaround, is in common problems.

Project

What is the license?

MIT.

How do I report a bug?

Open an issue with a minimal example that reproduces the problem, preferably a single-page HTML file. Security vulnerabilities do not go in a public issue: see how to report one.

How do I ask for a new feature?

Open a proposal issue explaining the problem before the solution. What is out of scope today is listed in the roadmap, in what Voodoo.js is.

How do I contribute code?

npm install
npm test
npm run typecheck
npm run build
npm run size

The repository's CONTRIBUTING.md file has the rest: commit convention, folder structure and what review expects.