repository·main·Indexed 27 days ago
https://github.com/vuejs/petite-vueA lightweight (~6kb) subset of Vue optimized for progressive enhancement. It is designed to sprinkle interactivity onto existing HTML rendered by server frameworks by mutating the DOM in place. Features include a minimal API with createApp(), v-scope, v-effect, and support for custom directives and components.
petite-vue is designed as a minimal, Vue-compatible alternative to Alpine.js for progressive enhancement. Key differences include:
petite-vue is approximately half the size of Alpine.petite-vue does not include a transition system.petite-vue aims to align with standard Vue behavior to reduce friction when migrating to full Vue applications.In petite-vue, components are implemented as functions that return a scope object.
Return an object containing state and methods. You can pass props to the function to initialize state.
To reuse a piece of HTML, include a $template key in the returned object. The value can be a template string or an ID selector for a <template> element. Using a <template> element is recommended for better performance.
function Counter(props) {
return {
$template: '#counter-template',
count: props.initialCount,
inc() {
this.count++
}
}
}<script type="module">
import { createApp } from 'https://unpkg.com/petite-vue?module'
function Counter(props) {
return {
$template: '#counter-template',
count: props.initialCount,
inc() {
this.count++
}
}
}
createApp({
Counter
}).mount()
</script>
<template id="counter-template">
My count is {{ count }}
<button @click="inc">++</button>
</template>
<!-- reuse it -->
<div v-scope="Counter({ initialCount: 1 })"></div>
<div v-scope="Counter({ initialCount: 2 })"></div>You can use petite-vue without a build step by loading it from a CDN.
To automatically find and initialize all elements with the v-scope attribute, use the init attribute in your script tag:
<script src="https://unpkg.com/petite-vue" defer init></script>
<div v-scope="{ count: 0 }">
{{ count }}
<button @click="count++">inc</button>
</div>If you prefer manual control, remove the init attribute and call createApp().mount() manually. You can use the global build or the ES module build.
Global Build (IIFE):
<script src="https://unpkg.com/petite-vue"></script>
<script>
PetiteVue.createApp().mount()
</script>ES Module Build:
<script type="module">
import { createApp } from 'https://unpkg.com/petite-vue?module'
createApp().mount()
</script><script src="https://unpkg.com/petite-vue" defer init></script>
<!-- anywhere on the page -->
<div v-scope="{ count: 0 }">
{{ count }}
<button @click="count++">inc</button>
</div>If you are using a server-side templating engine that also uses mustache syntax (e.g., {{ }}), you can change the petite-vue delimiters by passing $delimiters to the root scope in createApp().
createApp({
$delimiters: ['${', '}']
}).mount()petite-vue via a <script> tag, you can automatically initialize and mount the application to the document by adding the init attribute to the script tag. This is useful for quick setups without manual JavaScript calls.petite-vue evaluates JavaScript expressions in templates. If you mount petite-vue on a DOM region containing non-sanitized user-submitted HTML, it may be vulnerable to XSS attacks. To mitigate this:
petite-vue only processes DOM elements controlled by you.v-scope attributes.petite-vue uses new Function() to evaluate expressions. This may be blocked by strict CSP settings. There is no dedicated CSP build because the library relies on an expression parser to remain lightweight. If your project requires a strict CSP, consider using standard Vue with pre-compiled templates instead.
You can listen to lifecycle events for elements using the vue: prefix. The available events are @vue:mounted and @vue:unmounted.
<div
v-if="show"
@vue:mounted="console.log('mounted on: ', $el)"
@vue:unmounted="console.log('unmounted: ', $el)"
></div>To limit petite-vue to a specific region of the page, pass a CSS selector or a DOM element to the .mount() method. This allows you to run multiple independent petite-vue applications on the same page.
createApp().mount('#only-this-div')Custom directives are registered using .directive(name, handler). The handler receives a context object (ctx) containing:
el: The element the directive is bound to.exp: The raw value expression (e.g., x in v-dir="x").arg: The argument (e.g., foo in v-dir:foo).modifiers: An object of modifiers (e.g., { mod: true } for v-dir.mod).get(): Evaluates the expression and returns its value.get(expression): Evaluates an arbitrary expression in the current scope.effect(fn): Runs a reactive effect that re-runs when get() values change.Returning a function from the handler allows for cleanup when the element is unmounted.
const myDirective = (ctx) => {
// ... access ctx.el, ctx.exp, etc.
ctx.effect(() => {
console.log(ctx.get())
})
return () => {
// cleanup
}
}
createApp().directive('my-dir', myDirective).mount()The v-effect directive allows you to execute reactive inline statements. The code inside the directive will re-run whenever any reactive data source used within it changes.
<div v-scope="{ count: 0 }">
<div v-effect="$el.textContent = count"></div>
<button @click="count++">++</button>
</div>The createApp function accepts a data object that serves as the root scope for all expressions in the application. This object can contain reactive properties, getters, and methods.
When using v-scope on an element, you can omit the value if the scope is already provided by the root createApp configuration.
<script type="module">
import { createApp } from 'https://unpkg.com/petite-vue?module'
createApp({
// exposed to all expressions
count: 0,
// getters
get plusOne() {
return this.count + 1
},
// methods
increment() {
this.count++
}
}).mount()
</script>
<!-- v-scope value can be omitted -->
<div v-scope>
<p>{{ count }}</p>
<p>{{ plusOne }}</p>
<button @click="increment">increment</button>
</div>nextTick to wait for the next DOM update cycle. This is useful when you need to perform an action after petite-vue has finished updating the DOM in response to state changes.