NativeDocument

A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features

NativeDocument combines the familiarity of vanilla JavaScript with the power of modern reactivity. No compilation, no virtual DOM, just pure JavaScript with an intuitive API.

Why NativeDocument?

Note: NativeDocument works best with a bundler (Vite, Webpack, Rollup) for tree-shaking and optimal bundle size. The CDN version includes all features

Instant Start

<script src="https://cdn.jsdelivr.net/gh/afrocodeur/native-document/dist/native-document.min.js"></script>

Familiar API

import { Div, Button } from 'native-document/elements';
import { Observable } from 'native-document';

// CDN
// const { Div, Button } = NativeDocument.elements;
// const { Observable } = NativeDocument;

const count = Observable(0);

const App = Div({ class: 'app' }, [
    Div([ 'Count ', count]),
    Button('Increment').nd.onClick(() => count.set(count.val() + 1))
]);

document.body.appendChild(App);

Complete Features

• Native reactivity with observables
• Global store for state management
• Built-in conditional rendering
• Full-featured router (hash, history, memory modes)
• Advanced debugging system
• Automatic memory management via FinalizationRegistry

Quick Installation

Option 1: CDN (Instant Start)

<script src="https://cdn.jsdelivr.net/gh/afrocodeur/native-document/dist/native-document.min.js"></script>
<script>
  const { Div } = NativeDocument.elements
  const { Observable } = NativeDocument
  // Your code here
</script>

Option 2: Vite Template (Complete Project)

npx degit afrocodeur/native-document-vite my-app
cd my-app
npm install
npm run start

Option 3: NPM/Yarn

npm install native-document
# or
yarn add native-document

Quick Example

import { Div, Input, Button, ShowIf, ForEach } from 'native-document/elements'
import { Observable } from 'native-document'

// CDN
// const { Div, Input, Button, ShowIf, ForEach } = NativeDocument.elements;
// const { Observable } = NativeDocument;

// Reactive state
const todos = Observable.array([])
const newTodo = Observable('')

// Todo Component
const TodoApp = Div({ class: 'todo-app' }, [

    // Input for new todo
    Input({ placeholder: 'Add new task...', value: newTodo }),

    // Add button
    Button('Add Todo').nd.onClick(() => {
        if (newTodo.val().trim()) {
            todos.push({ id: Date.now(), text: newTodo.val(), done: false })
            newTodo.set('')
        }
    }),

    // Todo list
    ForEach(todos, (todo, index) =>
        Div({ class: 'todo-item' }, [
            Input({ type: 'checkbox', checked: todo.done }),
            `${todo.text}`,
            Button('Delete').nd.onClick(() => todos.splice(index.val(), 1))
        ]), (item) => item.id ), // Key function - use unique identifier

    // Empty state
    ShowIf(
        todos.check(list => list.length === 0),
        Div({ class: 'empty' }, 'No todos yet!')
    )
]);

document.body.appendChild(TodoApp)

Core Concepts

Observables

Reactive data that automatically updates the DOM:

import { Div } from 'native-document/elements'
import { Observable } from 'native-document'

// CDN
// const { Div  } = NativeDocument.elements;
// const { Observable } = NativeDocument;

const user = Observable({ name: 'John', age: 25 });
const greeting = Observable.computed(() => `Hello ${user.$value.name}!`, [user])
// Or const greeting = Observable.computed(() => `Hello ${user.val().name}!`, [user])

document.body.appendChild(Div(greeting));

// Direct mutation won't trigger updates
user.name = 'Fausty';

// These will trigger updates:
user.$value = { ...user.$value, name: ' Hermes!' };
user.set(data => ({ ...data, name: 'Hermes!' }));
user.set({ ...user.val(), name: 'Hermes!' });

Elements

Familiar HTML element creation with reactive bindings:

import { Div, Button } from 'native-document/elements'
import { Observable } from 'native-document'

// CDN
// const { Div, Button  } = NativeDocument.elements;
// const { Observable } = NativeDocument;

const App  = function() {
    const isVisible = Observable(true)
    
    return Div([
        Div({
            class: { 'hidden': isVisible.check(v => !v) },
            style: { opacity: isVisible.check(v => v ? 1 : 0.2) }
        }, 'Content'),
        Button('Toggle').nd.onClick(() => isVisible.set(v => !v)),
    ]);
};

document.body.appendChild(App());

Conditional Rendering

Built-in components for dynamic content:

ShowIf(user.check(u => u.isLoggedIn), 
  Div('Welcome back!')
)

Match(theme, {
  'dark': Div({ class: 'dark-mode' }),
  'light': Div({ class: 'light-mode' })
})

Switch(condition, onTrue, onFalse)

When(condition)
    .show(onTrue)
    .otherwise(onFalse)

List Rendering

Efficient rendering of lists with automatic updates:

import { ForEach, Div } from 'native-document/elements'
import { Observable } from 'native-document'

const items = Observable.array(['Apple', 'Banana', 'Cherry'])

ForEach(items, (item, index) => 
    Div([index, '. ', item])
)

// With object arrays - use key function
const users = Observable.array([
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
])

ForEach(users, (user) => 
    Div(user.name),
    (user) => user.id  // Key for efficient updates
)

Documentation

• Getting Started - Installation and first steps
• Core Concepts - Understanding the fundamentals
• Observables - Reactive state management
• Elements - Creating and composing UI
• Conditional Rendering - Dynamic content
• List Rendering - List Rendering
• Routing - Navigation and URL management
• State Management - Global state patterns
• Lifecycle Events - Lifecycle events
• NDElement - Native Document Element
• Extending NDElement - Custom Methods Guide
• Advanced Components - Template caching and singleton views
• Args Validation - Function Argument Validation
• Memory Management - Memory management
• Anchor - Anchor

Utilities

• Cache - Lazy initialization and singleton patterns
• NativeFetch - HTTP client with interceptors
• Filters - Data filtering helpers

Key Features Deep Dive

Performance Optimized

• Direct DOM manipulation (no virtual DOM overhead)
• Automatic batching of updates
• Lazy evaluation of computed values
• Efficient list rendering with keyed updates

Developer Experience

import { ArgTypes } from 'native-document'

// Built-in debugging
Observable.debug.enable()

// Argument validation
const createUser = (function (name, age) {
  // Auto-validates argument types
}).args(ArgTypes.string('name'), ArgTypes.number('age'))


const SafeApp = App.errorBoundary((error, { caller, args }) => {
    return Div({ class: 'error' }, [
        'An error occurred: ',
        error.message
    ])
});

document.body.appendChild(SafeApp());

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/afrocodeur/native-document
cd native-document
npm install
npm run dev

License

MIT © AfroCodeur

❤️ Support the Project

NativeDocument is developed and maintained in my spare time.
If it helps you build better applications, consider supporting its development:

You can also support the project via crypto donations:

• USDT (TRC20)
• USDT (BSC)
• USDC (Base)

0xCe426776DDb07256aBd58c850dd57041BC85Ea7D

Your support helps me:

• Maintain and improve NativeDocument
• Write better documentation and examples
• Fix bugs and ship new features
• Produce tutorials and learning content

Thanks for your support! 🙏

Acknowledgments

Thanks to all contributors and the JavaScript community for inspiration.

Ready to build with native simplicity? Get Started ->