Naja AJAX Library for Nette Framework

Common errors

• Uncaught TypeError: naja.initialize is not a function

  cause Attempting to call `initialize()` on an incorrectly imported or undefined Naja object.
  fix Ensure `import naja from 'naja';` is at the top of your script and that the script is executed after Naja is loaded and parsed as an ES Module.

• Uncaught ReferenceError: naja is not defined

  cause Naja's global object is not available when the script attempts to access it, usually due to missing or incorrect module import.
  fix Verify that Naja is correctly imported as a module (`import naja from 'naja';`) and that your build/runtime environment supports ES Modules. Avoid relying on a globally exposed `naja` without proper import.

• Cannot read properties of undefined (reading 'registerFactory') for custom extensions

  cause Attempting to access or extend Naja's internal components (like handlers or factories) in a way that is incompatible with Naja 3.x's refactored internals.
  fix Review the Naja 3.x documentation for updated APIs and extension points. The internals for snippet caching and handler registration might have changed, requiring updates to custom extensions.

Warnings

• breaking Naja 3.0 introduced significant internal changes to the snippet cache, which might alter behavior for advanced users or those with custom extensions. Thorough testing of existing applications with Naja 3.x is strongly recommended.
  Fix: Review any custom snippet handlers or extensions that interact directly with Naja's internal cache mechanisms. Test thoroughly to identify any regressions or changed behavior.
• breaking As of Naja 3.2.0, UI binding to forms has been simplified. Naja no longer binds directly to individual submitter elements (like buttons) but instead listens only to the `submit` event on the form itself. This can affect custom event handlers or extensions that previously relied on direct binding to submitter elements.
  Fix: Adjust custom logic to listen for the `submit` event on the form element or use the `UIHandler.submitForm()` helper method (preferably `form.requestSubmit()` in modern browsers) for manual form submissions.
• gotcha Naja is primarily designed as an ES Module (ESM). Using CommonJS `require()` to import Naja can lead to `TypeError: naja.initialize is not a function` or similar module resolution errors.
  Fix: Always use `import naja from 'naja';` in your JavaScript/TypeScript files. Ensure your build system or Node.js environment is configured to handle ESM correctly.

Install

• npm install naja npm
• yarn add naja yarn
• pnpm add naja pnpm

Imports

• naja
  wrong:

  const naja = require('naja');

  correct:

  import naja from 'naja';

  Naja is an ESM-first library. Direct `require()` is not supported. Use dynamic import if CJS context is unavoidable.
• Event types
  wrong:

  import { InteractionEvent, BuildStateEvent } from 'naja';

  correct:

  import type { InteractionEvent, BuildStateEvent } from 'naja';

  Since v3.2.1, Naja exports all event types for enhanced TypeScript strictness. These should be imported using `import type`.
• Naja instance (global)
  wrong:

  naja.initialize(); // without import

  correct:

  import naja from 'naja'; naja.initialize();

  Naja is typically imported as a module. Relying on a global `naja` object without an explicit import (e.g., from an older script tag) may not work as expected in a modern module environment.

Quickstart

Demonstrates how to initialize Naja and subscribe to its core lifecycle events to handle Nette AJAX interactions and custom snippet updates.

import naja from 'naja';

document.addEventListener('DOMContentLoaded', () => {
    // Initialize Naja. This sets up event listeners for AJAX interactions
    // on elements like <a data-nette-ajax> and <form data-nette-ajax>.
    naja.initialize();

    // Listen to Naja's lifecycle events for debugging or custom logic.
    naja.addEventListener('init', () => {
        console.log('Naja initialized and ready to handle Nette AJAX requests.');
    });

    naja.addEventListener('interaction', (event) => {
        console.log('AJAX interaction started:', event.detail.element.tagName, event.detail.url);
    });

    naja.addEventListener('start', (event) => {
        console.log('AJAX request is about to be sent.');
        // You could show a loading spinner here
    });

    naja.addEventListener('success', (event) => {
        console.log('AJAX request successful.');
        // Hide loading spinner
    });

    naja.addEventListener('error', (event) => {
        console.error('AJAX request failed:', event.detail.error);
        // Handle error, e.g., display an error message
    });

    // Example: Custom snippet handler for specific element updates
    naja.snippetHandler.addEventListener('afterUpdate', (event) => {
        const { snippet, content } = event.detail;
        if (snippet && snippet.id === 'my-dynamic-content') {
            document.getElementById('my-dynamic-content').innerHTML = content;
            console.log(`Snippet #${snippet.id} updated.`);
        }
    });
});