{"id":11377,"library":"naja","title":"Naja AJAX Library for Nette Framework","description":"Naja is a modern, full-featured client-side AJAX library specifically designed for seamless integration with the Nette Framework. It provides robust capabilities for handling asynchronous requests, managing browser history states, and dynamically updating UI snippets, enabling developers to build highly interactive web applications with minimal JavaScript boilerplate. Currently stable at version 3.3.3, Naja maintains an active release cadence, frequently delivering minor enhancements and bug fixes. Key differentiators include its tight coupling with Nette's server-side AJAX responses, thorough testing across modern browsers (Chromium, Firefox, WebKit), and a strong focus on providing a reliable, performant AJAX experience tailored for the Nette ecosystem, allowing for progressive enhancement of traditional server-rendered applications. It is written using modern JavaScript and compiled for broad browser compatibility.","status":"active","version":"3.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/naja-js/naja","tags":["javascript","nette","ajax","history"],"install":[{"cmd":"npm install naja","lang":"bash","label":"npm"},{"cmd":"yarn add naja","lang":"bash","label":"yarn"},{"cmd":"pnpm add naja","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Naja is an ESM-first library. Direct `require()` is not supported. Use dynamic import if CJS context is unavoidable.","wrong":"const naja = require('naja');","symbol":"naja","correct":"import naja from 'naja';"},{"note":"Since v3.2.1, Naja exports all event types for enhanced TypeScript strictness. These should be imported using `import type`.","wrong":"import { InteractionEvent, BuildStateEvent } from 'naja';","symbol":"Event types","correct":"import type { InteractionEvent, BuildStateEvent } from 'naja';"},{"note":"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.","wrong":"naja.initialize(); // without import","symbol":"Naja instance (global)","correct":"import naja from 'naja'; naja.initialize();"}],"quickstart":{"code":"import naja from 'naja';\n\ndocument.addEventListener('DOMContentLoaded', () => {\n    // Initialize Naja. This sets up event listeners for AJAX interactions\n    // on elements like <a data-nette-ajax> and <form data-nette-ajax>.\n    naja.initialize();\n\n    // Listen to Naja's lifecycle events for debugging or custom logic.\n    naja.addEventListener('init', () => {\n        console.log('Naja initialized and ready to handle Nette AJAX requests.');\n    });\n\n    naja.addEventListener('interaction', (event) => {\n        console.log('AJAX interaction started:', event.detail.element.tagName, event.detail.url);\n    });\n\n    naja.addEventListener('start', (event) => {\n        console.log('AJAX request is about to be sent.');\n        // You could show a loading spinner here\n    });\n\n    naja.addEventListener('success', (event) => {\n        console.log('AJAX request successful.');\n        // Hide loading spinner\n    });\n\n    naja.addEventListener('error', (event) => {\n        console.error('AJAX request failed:', event.detail.error);\n        // Handle error, e.g., display an error message\n    });\n\n    // Example: Custom snippet handler for specific element updates\n    naja.snippetHandler.addEventListener('afterUpdate', (event) => {\n        const { snippet, content } = event.detail;\n        if (snippet && snippet.id === 'my-dynamic-content') {\n            document.getElementById('my-dynamic-content').innerHTML = content;\n            console.log(`Snippet #${snippet.id} updated.`);\n        }\n    });\n});","lang":"javascript","description":"Demonstrates how to initialize Naja and subscribe to its core lifecycle events to handle Nette AJAX interactions and custom snippet updates."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to call `initialize()` on an incorrectly imported or undefined Naja object.","error":"Uncaught TypeError: naja.initialize is not a function"},{"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.","cause":"Naja's global object is not available when the script attempts to access it, usually due to missing or incorrect module import.","error":"Uncaught ReferenceError: naja is not defined"},{"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.","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.","error":"Cannot read properties of undefined (reading 'registerFactory') for custom extensions"}],"ecosystem":"npm"}