@arikajs/view

v0.10.19

Published

a month ago

Server-side rendering and template engine for the ArikaJS framework.

Downloads

331

0High
0Medium
0Low

prakashtank

arikajs framework node.js typescript view

Arika View v2.0 ⚡

@arikajs/view is a high-performance, server-first template engine designed for the ArikaJS ecosystem. It provides an instant Single-Page Application (SPA) experience using a native Node.js compiler, eliminating the complexity of heavy client-side frameworks.

⚡ Server-Driven Native Performance

1️⃣ Zero-Runtime Overhead (Strict Mode)

Arika View uses a highly optimized V8 compiler that maps your server variables directly into native function arguments. By eliminating the with(_data) runtime lookup used by traditional engines like EJS, we achieve near-zero latency rendering.

Your template variables (like {{ $user.name }}) are JIT-compiled into pure native JavaScript functions, making UI rendering mathematically as fast as the V8 engine itself.

// Enabled by default in modern ArikaJs apps natively inside Engine.ts!
view.config({
    strict: true 
});

2️⃣ HTML-Over-The-Wire (`@spa`)

Get the instant, smooth Single-Page Application (SPA) feel of React—without writing a single line of React, installing heavy frontend packages, or managing Vite plugins. Simply drop the @spa directive into your global layout's <head> or <body>:

<head>
    <title>My Super Fast App</title>
    <!-- Instantly turn your entire ArikaJs application into an SPA! -->
    @spa
</head>

What @spa does mathematically:

Intercepts all link clicks entirely to stop "Hard Browser Reloads" (no more flashing white screens).
Fetches the compiled HTML silently in the background and seamlessly swaps the DOM elements.
Automatically triggers Native Browser View Transitions (providing iOS-like crossfades and slides between pages) automatically!

🚀 Core Architecture

Arika View features a completely customized compiler stack:

Lexer: Intelligent tokenization of .ark.html files.
Parser: Builds a robust Abstract Syntax Tree (AST) for deeply nested loops/blocks.
Directive Registry: Modular system for extending templating language.
Code Generator: Produces highly optimized, async-ready JavaScript buffers.

🛡️ Security & XSS Protection

Everything in Arika View is Safe by Default.

Escaped Output (Standard)

All values inside double curly braces are automatically escaped to prevent Cross-Site Scripting (XSS) attacks.

{{ "<script>alert(1)</script>" }}
<!-- Renders as: &lt;script&gt;alert(1)&lt;/script&gt; -->

Raw Output (Unsafe)

If you specifically need to output raw HTML, use the {!! !!} syntax. Use this only for content you trust.

{!! "<h1>Trusted Title</h1>" !!}

✨ Key Features

Pure JavaScript & Blade Syntax

Arika View natively embraces JavaScript and traditional PHP-style variables. You can write {{ $user.name }} or {{ user.name }} seamlessly — if it's valid JS, it's valid in your template.

@if ($user?.isAdmin && $posts.length > 0)
    <p>Welcome back, Admin!</p>
@endif

Type-Safe View Data

Leverage TypeScript's power in your backend controllers smoothly crossing into your views.

interface HomeData {
    title: string;
    user: { name: string };
}

await view.render<HomeData>('home', {
    title: 'ArikaJS',
    user: { name: 'Prakash' }
});

Modern Components (`<x-`)

Stop using clunky syntax. Build massive apps using modern, HTML-like components.

<x-alert type="danger" :dismissible="true">
    <x-slot name="title">Warning!</x-slot>
    Something went wrong.
</x-alert>

Fragments (HTMX Ready ⚡)

If you don't use @spa, you can manually render only a specific part of a template—perfect for custom HTMX APIs or partial reloads.

@fragment('sidebar')
    <nav>...</nav>
@endfragment

await view.renderFragment('dashboard', 'sidebar');

Server Actions (@action) — Zero-API Development 🚀

Arika View eliminates the need for manual API routing. Call your controller methods directly from your HTML and handle the response with a reactive fluent API.

1. Define the Action

Inside any form, use the @action directive to point to a controller method.

<form @action="updateProfile">
    <input name="name" value="{{ $user.name }}">
    <button type="submit">Save Changes</button>
</form>

2. Handle the Lifecycle

Use the actions global object to add interactivity without writing complex fetch logic.

actions.updateProfile
    .optimistic((data) => {
        document.querySelector('.display-name').innerText = data.name;
    })
    .start(() => {
        myButton.loading = true;
    })
    .finish((response) => {
        toast.success(response.message);
    })
    .error((errors) => {
        alert('Validation failed!');
    })
    .always(() => {
        myButton.loading = false;
    });

🚀 Single Page Application (@spa)

The @spa directive transforms your app into a high-performance SPA with zero configuration.

<body @spa>
    <!-- Automatic speed boost enabled -->
</body>

Native Performance Features

State Preservation: Add data-preserve to any element (inputs, videos, sidebars) to keep them alive across page transitions.

<input name="search" data-preserve>

Scroll Restoration: Automatically remembers and restores your scroll position per route.
Predictive Navigation: Use @prefetch on links to load them as soon as the user hovers, making transitions feel instant.

<a href="/profile" @prefetch>View Profile</a>

View Transitions: Uses the native browser View Transition API for smooth, fluid animations.
Smart Lifecycle: Listen for arika:spa:start and arika:spa:end events for custom loaders.

📡 Live Fragments (@fetch)

Create reactive UI components that handle their own data fetching and polling.

<div @fetch="/api/statistics" @interval="5000">
    <!-- This content will refresh every 5 seconds -->
    <p>Loading stats...</p>
</div>

Features

Automatic Polling: Use @interval(ms) to keep data fresh.
Focus Revalidation: Automatically refreshes content when the user returns to the tab.
SSR First: The initial content is rendered on the server, then the client takes over.
Fragment Support: Works perfectly with Arika's @fragment system for partial updates.

⚡ Template-Level Caching (@cache)

Boost performance by caching expensive HTML fragments. Perfect for sidebars, navigation, or heavy data-driven components.

@cache('global_sidebar', 3600)
    <!-- This block only renders once per hour -->
    @foreach($heavy_data as $item)
        <div>{{ $item->compute() }}</div>
    @endforeach
@endcache

🌊 Streaming SSR (Zero-Delay Rendering)

ArikaJS supports native streaming SSR, allowing you to stream the HTML markup to the browser as it's being generated. This significantly improves the Largest Contentful Paint (LCP) and Time to First Byte (TTFB) for data-heavy pages.

// In your Controller
public async index({ view }) {
    // Instead of view.render(), use view.stream()
    return await view.stream('homepage', { 
        data: heavyDatabaseQuery() 
    });
}

👉 Why Streaming? The server can send the <head> and top-level layout immediately while waiting for slow database queries or asynchronous operations inside the view.

🌍 Edge-Ready Architecture (Web Streams)

ArikaJS is built for the modern edge. The View Engine is Cross-Runtime Compatible, supporting standard Web Streams (Fetch API) out of the box. This means you can deploy your interactive SSR applications to:

Cloudflare Workers
Vercel Edge Functions
Deno / Bun / AWS Lambda

🛡 Zero-JS Validation Mapping

Forget writing manual fetch error handlers. ArikaJS automatically maps server-side validation errors to your UI.

<form @action('register') method="POST">
    <input name="email">
    <!-- This updates automatically if validation fails -->
    @error('email') <span class="error">{{ $message }}</span> @enderror
</form>

When the server returns a 422 error, the Arika SPA engine identifies the @error fragments and live-patches them with the new messages instanty.

📂 Zero-API File Uploads

Server Actions natively support multipart/form-data. Uploading files is as simple as adding an input.

<form @action('upload') method="POST" enctype="multipart/form-data">
    <input type="file" name="avatar">
    <button>Upload</button>
</form>

In your controller, the file is ready for you:

public async upload({ request }) {
    const file = request.file('avatar');
    await file.store('avatars');
}

🌐 SEO & Meta System

Managing social media tags and SEO is dead simple with the @meta directive.

@meta({
  title: "Welcome to ArikaJS",
  description: "The high-performance interactivity framework",
  image: "https://arika.js/og-image.png"
})

This automatically generates all necessary <title>, <meta name="description">, and OpenGraph tags. To render them, simply place the @head directive in your base layout's <head>:

<head>
  @head
  <!-- Your other assets -->
</head>

🛠 Elite Dev Experience (DX)

ArikaJS includes premium debugging tools built-in:

Error Overlay: When a template fails, we show you the exact line in your .ark.html file, not just a cryptic JS stack trace.
Dev Inspector: Press Cmd+Shift+X and click any element to see exactly which view file and line generated it.
Hot Reload (HMR): Changes to your views are live-patched into the browser without losing application state or needing a full refresh.

🛠 Directives Reference

| Directive | Description | |-----------|-------------| | @meta(obj) | [NEW] Declaratively set page titles, descriptions, and social images. | | @head | [NEW] Renders all collected SEO and OpenGraph tags into the document head. | | @spa | [NEW] Instantly upgrades the frontend site to a Single Page Application. | | @if, @elseif, @else | Standard conditional logic. | | @unless | Inverse of @if. | | @for, @foreach | Standard JS and PHP style loops internally optimized. | | @each(view, data, item, empty) | Render a view for each item in a collection. | | @switch, @case, @default | Switch statement support. | | @break, @continue | Control loop execution. | | @auth, @guest | Conditional rendering based on user session. | | @once | Ensure a block is only rendered once per request. | | @verbatim | Stop parsing content inside the block. | | @push, @stack, @prepend | Manage assets and scripts across layouts. | | @await(promise) | Native async Promise support inside templates! |

🔌 Advanced Ecosystem

View Composers

Inject data into specific views automatically before they are rendered globally.

view.composer('dashboard', async (data) => {
    data.notifications = await getNotifications();
});

Global Helpers

Define custom functions accessible natively inside every template.

view.helper('formatDate', (date) => new Intl.DateTimeFormat().format(date));

Usage: {{ formatDate(user.createdAt) }}

Custom Directives API

Extend Arika View with your own robust functionality.

view.directive('uppercase', (exp) => `_output += String(${exp}).toUpperCase();`);

📁 File Structure & Extension

Arika View exclusively uses the .ark.html extension for all templates to trigger the internal AST Lexer.

resources/views/
├── layouts/
│   └── app.ark.html
├── auth/
│   ├── login.ark.html
│   └── register.ark.html
└── welcome.ark.html

💻 CLI Integration

Generate views instantly with the fast Arika CLI:

arika make:view home
# Generates resources/views/home.ark.html

🧠 Philosophy

"Arika View turns your templates into native Node.js machine-code, making UI rendering mathematically as fast as the Javascript Engine itself."

License

MIT