https://github.com/vincenthirtz/pulse-js-framework
A declarative DOM framework with CSS selector-based structure
https://github.com/vincenthirtz/pulse-js-framework
framework javascript mobile web
Last synced: 4 months ago
JSON representation
A declarative DOM framework with CSS selector-based structure
- Host: GitHub
- URL: https://github.com/vincenthirtz/pulse-js-framework
- Owner: vincenthirtz
- License: mit
- Created: 2026-01-29T12:26:49.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-31T16:41:29.000Z (5 months ago)
- Last Synced: 2026-01-31T21:29:46.786Z (5 months ago)
- Topics: framework, javascript, mobile, web
- Language: JavaScript
- Homepage: https://pulse-js.fr
- Size: 642 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pulse Framework
[](https://github.com/vincenthirtz/pulse-js-framework/actions/workflows/ci.yml)
[](https://codecov.io/gh/vincenthirtz/pulse-js-framework)
[](https://app.netlify.com/projects/pulse-js/deploys)
No build. No dependencies. Just JavaScript.
## Features
- **CSS Selector Syntax** - Create DOM elements using familiar CSS selectors
- **Reactive Pulsations** - Automatic UI updates when state changes
- **Custom DSL** - Optional `.pulse` file format for cleaner code
- **No Build Required** - Works directly in the browser
- **Lightweight** - Minimal footprint, maximum performance
- **Router & Store** - Built-in SPA routing and state management
- **Form Handling** - Validation, async validators, field arrays
- **Async Primitives** - useAsync, useResource, usePolling with SWR caching
- **Server-Side Rendering** - Full SSR with hydration and async data fetching
- **Hot Module Replacement** - Full HMR with state preservation
- **Mobile Apps** - Build native Android & iOS apps (zero dependencies)
- **TypeScript Support** - Full type definitions for IDE autocomplete
- **DevTools** - Time-travel debugging, dependency graph visualization
## Installation
```bash
npm install pulse-js-framework
```
## Quick Start
### Create a new project
```bash
npx pulse-js-framework create my-app
cd my-app
npm install
npm run dev
```
### Or with TypeScript
```bash
npx pulse-js-framework create my-app --typescript
cd my-app
npm install
npm run dev
```
### Or from a template
Create projects from built-in example apps:
```bash
# E-commerce app (products, cart, checkout)
npx pulse-js-framework create my-shop --ecommerce
# Todo app (filtering, local storage)
npx pulse-js-framework create my-todos --todo
# Blog (posts, sidebar, navigation)
npx pulse-js-framework create my-blog --blog
# Chat app (messages, users, emoji picker)
npx pulse-js-framework create my-chat --chat
# Dashboard (data visualization)
npx pulse-js-framework create my-dashboard --dashboard
```
### Or use directly
```javascript
import { pulse, effect, el, mount } from 'pulse-js-framework';
// Create reactive state
const count = pulse(0);
// Build UI with CSS selector syntax
function Counter() {
const div = el('.counter');
const display = el('h1');
effect(() => {
display.textContent = `Count: ${count.get()}`;
});
const increment = el('button.btn', '+');
increment.onclick = () => count.update(n => n + 1);
div.append(display, increment);
return div;
}
mount('#app', Counter());
```
## CSS Selector Syntax
```javascript
el('div') //
el('.container') //
el('#app') //
el('button.btn.primary') //
el('input[type=text]') //
el('h1', 'Hello World') // Hello World
```
## Reactivity
```javascript
import { pulse, effect, computed, batch } from 'pulse-js-framework';
const firstName = pulse('John');
const lastName = pulse('Doe');
// Computed values
const fullName = computed(() => `${firstName.get()} ${lastName.get()}`);
// Effects auto-run when dependencies change
effect(() => console.log(`Hello, ${fullName.get()}!`));
firstName.set('Jane'); // Logs: "Hello, Jane Doe!"
// Batch updates (effects run once)
batch(() => {
firstName.set('John');
lastName.set('Smith');
});
```
## .pulse File Format
```pulse
@page Counter
state {
count: 0
}
view {
.counter {
h1 "Count: {count}"
button @click(count++) "+"
button @click(count--) "-"
}
}
style {
.counter { text-align: center; padding: 20px }
}
```
See [Pulse DSL documentation](docs/pulse-dsl.md) for full syntax reference.
## CLI Commands
```bash
# Project Creation
pulse create # Create new project
pulse create --typescript # Create TypeScript project
pulse create --ecommerce # Create from E-Commerce template
pulse create --todo # Create from Todo App template
pulse create --blog # Create from Blog template
pulse create --chat # Create from Chat template
pulse create --dashboard # Create from Dashboard template
pulse init --typescript # Initialize in current directory
# Development
pulse dev [port] # Start dev server (default: 3000)
pulse build # Build for production
pulse preview [port] # Preview production build
pulse compile # Compile .pulse file
# Code Quality
pulse lint [files] # Validate .pulse files
pulse lint --fix # Auto-fix fixable issues
pulse format [files] # Format .pulse files
pulse analyze # Analyze bundle
# Testing
pulse test # Run tests with Node.js test runner
pulse test --coverage # Run tests with coverage
pulse test --watch # Watch mode
pulse test --create # Generate test file
# Project Tools
pulse doctor # Run project diagnostics
pulse doctor --verbose # Detailed diagnostics
# Creating .pulse Files
pulse new # Create component (src/components/.pulse)
pulse new --type page # Create page (src/pages/.pulse)
pulse new --type layout # Create layout (src/layouts/.pulse)
pulse new --props # Include props section
# Scaffolding
pulse scaffold component # Generate component
pulse scaffold page # Generate page
pulse scaffold store # Generate store module
pulse scaffold hook # Generate custom hook
pulse scaffold service # Generate API service
pulse scaffold context # Generate context provider
pulse scaffold layout # Generate layout component
# Documentation
pulse docs --generate # Generate API docs (Markdown)
pulse docs --generate -f html # Generate HTML docs
pulse docs --generate -f json # Generate JSON docs
```
See [CLI documentation](docs/cli.md) for full command reference.
## Core Modules
### Router
```javascript
import { createRouter, lazy } from 'pulse-js-framework/runtime/router';
const router = createRouter({
routes: {
'/': HomePage,
'/users/:id': UserPage,
'/dashboard': lazy(() => import('./Dashboard.js'))
}
});
```
### Store
```javascript
import { createStore, createActions } from 'pulse-js-framework/runtime/store';
const store = createStore({ user: null, theme: 'light' }, { persist: true });
const actions = createActions(store, {
login: (store, user) => store.user.set(user)
});
```
### Form
```javascript
import { useForm, validators } from 'pulse-js-framework/runtime/form';
const { fields, handleSubmit, isValid } = useForm(
{ email: '', password: '' },
{
email: [validators.required(), validators.email()],
password: [validators.required(), validators.minLength(8)]
}
);
```
### Async
```javascript
import { useAsync, useResource } from 'pulse-js-framework/runtime/async';
const { data, loading } = useAsync(() => fetch('/api/users').then(r => r.json()));
const users = useResource('users', fetchUsers, { refreshInterval: 30000 });
```
### Accessibility
```javascript
import {
// Announcements
announce, createAnnouncementQueue,
// Focus management
trapFocus, onEscapeKey, createFocusVisibleTracker,
// User preferences
prefersReducedMotion, prefersReducedTransparency, forcedColorsMode,
// ARIA widgets
createModal, createTooltip, createAccordion, createMenu,
// Color contrast
getContrastRatio, meetsContrastRequirement,
// Validation
validateA11y
} from 'pulse-js-framework/runtime/a11y';
// Screen reader announcements
announce('Item saved successfully');
// Accessible modal dialog
const modal = createModal(dialog, { labelledBy: 'title', closeOnBackdropClick: true });
modal.open();
// Check color contrast (WCAG)
const ratio = getContrastRatio('#333', '#fff'); // 12.63
meetsContrastRequirement(ratio, 'AA'); // true
```
See [Accessibility documentation](docs/accessibility.md) for full guide.
See [API documentation](docs/api.md) for full reference.
## Mobile Apps
Build native Android and iOS apps:
```bash
pulse mobile init
pulse build
pulse mobile build android
pulse mobile run android
```
```javascript
import { createNativeStorage, NativeUI } from 'pulse-js-framework/runtime/native';
const storage = createNativeStorage();
const theme = storage.get('theme', 'light');
NativeUI.toast('Hello from native!');
```
See [Mobile documentation](docs/mobile.md) for full guide.
## IDE Extensions
### VS Code
```bash
cd vscode-extension && bash install.sh
```
### IntelliJ IDEA / WebStorm
```bash
cd intellij-plugin && ./gradlew buildPlugin
```
Features: Syntax highlighting, code snippets, bracket matching.
## TypeScript Support
Full type definitions included:
```typescript
import { pulse, Pulse } from 'pulse-js-framework/runtime';
import { createRouter, Router } from 'pulse-js-framework/runtime/router';
const count: Pulse = pulse(0);
```
## Examples
| Example | Description |
|---------|-------------|
| [Todo App](examples/todo) | Task management with filters |
| [Blog](examples/blog) | CRUD, categories, search |
| [Chat App](examples/chat) | Real-time messaging |
| [E-commerce](examples/ecommerce) | Shopping cart |
| [Dashboard](examples/dashboard) | Admin UI |
| [HMR Demo](examples/hmr) | Hot module replacement |
| [Router Demo](examples/router) | SPA routing |
| [Store Demo](examples/store) | State with undo/redo |
| [Electron App](examples/electron) | Desktop notes app |
## Server-Side Rendering
Pulse supports full SSR with hydration and async data fetching:
```javascript
// server.js
import { renderToString, serializeState } from 'pulse-js-framework/runtime/ssr';
import App from './App.js';
app.get('*', async (req, res) => {
const { html, state } = await renderToString(() => App(), {
waitForAsync: true // Wait for useAsync to resolve
});
res.send(`
${html}
window.__PULSE_STATE__ = ${serializeState(state)};
`);
});
// client.js
import { hydrate } from 'pulse-js-framework/runtime/ssr';
import App from './App.js';
hydrate('#app', () => App(), {
state: window.__PULSE_STATE__
});
```
## Documentation
- [API Reference](docs/api.md) - Complete API documentation
- [CLI Commands](docs/cli.md) - Command line interface
- [Pulse DSL](docs/pulse-dsl.md) - .pulse file syntax
- [Accessibility](docs/accessibility.md) - A11y guide and ARIA helpers
- [HTTP Client](docs/http.md) - Fetch wrapper with interceptors
- [WebSocket](docs/websocket.md) - Real-time with auto-reconnect
- [GraphQL](docs/graphql.md) - Queries, mutations, subscriptions
- [Context API](docs/context.md) - Dependency injection
- [DevTools](docs/devtools.md) - Debugging and profiling
- [Mobile Apps](docs/mobile.md) - Native Android & iOS
- [SSR](docs/ssr.md) - Server-side rendering and hydration
## License
MIT