mini-vue

name: mini-vue description: Guides the agent when working with the local mini-vue framework in this project. Use when the user mentions mini-vue, @mini-vue imports, JSX components in this repo, or asks about how to mount/render components using the custom mini-vue runtime.

Mini Vue (local framework) Skill

This project contains a small Vue-like runtime in the mini-vue directory, exposed via the @mini-vue alias. Use this skill whenever you are working inside this repo with components that import from @mini-vue.

When to Apply This Skill

Use these instructions when:

The user mentions mini-vue or @mini-vue
The code imports from @mini-vue (for example in src/App.tsx, src/main.tsx, or components)
The user asks how rendering, reactivity, or components work in this project
The user wants to add or modify components, state, or mounting logic using this custom framework

Project-Specific Conventions

@mini-vue is not the official Vue package; it is a local framework implemented in the mini-vue directory.
TypeScript and Vite are configured so that:
- @mini-vue resolves to mini-vue/index.ts
- jsxImportSource is set to @mini-vue
- JSX in .tsx files uses the custom runtime defined in mini-vue/jsx-runtime.ts
Example usage lives in src/:
- src/main.tsx mounts the root component using mount from @mini-vue.
- src/App.tsx and components under src/components/ demonstrate typical patterns.

Core mini-vue APIs

The public entrypoint mini-vue/index.ts re-exports the main primitives:

component: defines a component using a setup function
mount: mounts a VNode or root renderer into a DOM container
h / JSX runtime: creates virtual nodes used by the renderer
reactive: wraps arrays/objects to make them reactive
ref: wraps primitive values with a .value property
watchEffect: runs a reactive effect and re-runs it when dependencies change

`component` usage

Components are created by calling component(setup).
The setup function:
- Receives props (typed via generics if needed).
- Can return either:
  - A VNode directly, or
  - A render function that returns a VNode.
In this project, components typically return a render function that uses JSX:

import { component } from '@mini-vue'

const MyComponent = component((props: { message: string }) => {
  return () => (
    <div>{props.message}</div>
  )
})

export default MyComponent

Key details:

Components may be called with (props, key?).
The internal implementation uses a render scope with slots and keyed slots to reuse component instances across renders.

`mount` usage

The mount function accepts either:
- A VNode, or
- A root renderer function that returns a VNode.
In this project, the typical pattern is to pass a root component (created with component) as the first argument, and a DOM element as the second:

import { mount } from '@mini-vue'
import App from './App'

mount(App, document.getElementById('app'))

Behavior:

If the source is a function, mini-vue:
- Creates a root render scope via createRootRenderScope.
- Uses watchEffect to track reactivity.
- Calls renderWithRootScope to produce the next VNode tree.
- On the first run, it mounts the tree; on subsequent runs it calls patch(prevVNode, nextVNode) to update the DOM.
If the source is a VNode, it is mounted directly via mountVNode.

Reactivity Patterns

The project demonstrates reactivity in src/components/TodoList.tsx:

reactive is used for collections (arrays/objects) that should trigger re-renders when mutated:

import { reactive } from '@mini-vue'

const todoItems = reactive([
  { id: Date.now(), todo: 'Do something!', isDone: false },
])

// Mutations like push() are reactive:
todoItems.push({ id: Date.now(), todo: 'Another', isDone: false })

ref is used for primitive values:

import { ref } from '@mini-vue'

const newTodo = ref('')
newTodo.value = 'Buy milk'

Event handlers update refs and reactive state. The JSX event handlers (onInput, onClick, etc.) ultimately go through the props system in mini-vue/props.ts and are applied to DOM elements in mini-vue/mount.ts.

When modifying or adding components:

Prefer ref for single scalar values (string, number, boolean).
Prefer reactive for lists/objects that you'll mutate (push, splice, etc.).
Use watchEffect when you need side effects reacting to changes in reactive/refs.

JSX and VNode Basics

JSX is compiled using @mini-vue’s JSX runtime (mini-vue/jsx-runtime.ts).
The h function (and JSX) produce VNode objects with shape similar to:
- tag: string tag name
- props: prop bag
- children: array of strings or VNodes
mini-vue/mount.ts handles:
- Creating actual DOM elements (document.createElement)
- Applying props via applyProp from mini-vue/props.ts
- Recursively mounting children.

When writing JSX:

Use HTML tag names (div, button, input, etc.) for DOM elements.
Use PascalCase for components created with component.
Pass props and event handlers like in React/Vue JSX:

<input
  class="border border-black px-1 py-0.5 block mb-4"
  value={newTodo.value}
  onInput={handleInput}
/>

Example: Adding a New Component

To add a new component in this project:

Create a .tsx file under src/components/, e.g. NewItem.tsx.
Import component and any reactivity primitives needed from @mini-vue.
Define the component using a setup function that returns a render function.
Use JSX to describe the UI.
Import and render it from App.tsx or another component.

Example:

// src/components/NewItem.tsx
import { component } from '@mini-vue'

export default component((props: { label: string }) => {
  return () => (
    <span>{props.label}</span>
  )
})

// src/App.tsx
import { component } from '@mini-vue'
import NewItem from './components/NewItem'

export default component(() => {
  return () => (
    <div>
      <NewItem label="Hello mini-vue" />
    </div>
  )
})

Agent Guidance

When assisting in this project:

Do not treat @mini-vue as an external npm dependency; it is local code under mini-vue/.
Prefer using the existing primitives (component, mount, reactive, ref, watchEffect) rather than re-implementing core framework behavior.
When explaining behavior, reference the implementation files (mini-vue/component.ts, mini-vue/mount.ts, mini-vue/reactive.ts, etc.) instead of generic Vue/React internals.
Ensure new code:
- Stays consistent with current patterns in src/App.tsx and src/components/*.
- Respects the TypeScript configuration (jsxImportSource, paths, and strict mode).

Additional Resources

If you need more detail:

Inspect the implementation files under mini-vue/ for low-level behavior.
Look at src/components/TodoList.tsx and src/components/TodoItem.tsx for idiomatic usage examples in this repo.