codejarplus

[!TIP]

【2025-09-23】

纪念中国人民抗日战争暨世界反法西斯战争胜利 80 周年

Commemoration of the 80th Anniversary of the Victory of the Chinese People's War of Resistance Against Japanese Aggression and the World Anti-Fascist War

चीनी जनवादी प्रतिरोध युद्ध की 80वीं वर्षगांठ और जापानी आक्रमण विरोधी विश्व युद्ध की विजय का स्मरणोत्सव

Conmemoración del 80º Aniversario de la Victoria de la Guerra de Resistencia del Pueblo Chino contra la Agresión Japonesa y la Guerra Mundial Antifascista

Commémoration du 80e anniversaire de la victoire de la Guerre de résistance du peuple chinois contre l'agression japonaise et de la Guerre mondiale antifasciste

الذكرى الثمانون لانتصار حرب مقاومة الشعب الصيني ضد العدوان الياباني والحرب العالمية ضد الفاشية

জাপানি আগ্রাসনের বিরুদ্ধে চীনা জনগণের প্রতিরোধ যুদ্ধ এবং বিশ্ব ফ্যাসিবাদবিরোধী যুদ্ধের বিজয়ের ৮০তম বার্ষিকী উদযাপন

80-я годовщина Победы в Войне сопротивления китайского народа японским захватчикам и в Мировой антифашистской войне

Comemoração do 80º Aniversário da Vitória da Guerra de Resistência do Povo Chinês contra a Agressão Japonesa e a Guerra Mundial Antifascista

Gedenken an den 80. Jahrestag des Sieges im Widerstandskrieg des chinesischen Volkes gegen die japanische Aggression und im weltweiten antifaschistischen Krieg

中国人民抗日戦争並びに世界反ファシズム戦争勝利 80 周年記念

CodeJarPlus 🍯✨

English | 中文

A lightweight, modular, and extensible code editor for the modern web.

CodeJarPlus is an open-source project deeply refactored and functionally enhanced by WOODCOAL (木炭), based on the popular antonmedv/codejar. It not only fully inherits the lightweight and efficient nature of codejar (only a few KB after gzip), but also introduces a powerful modular plugin system, with built-in core plugins like line numbers and code marking, allowing the compact editor to have professional capabilities and extensibility comparable to an IDE.

✨ Core Features

• Powerful Plugin System: Easily mount or unmount features for an editor instance via the addPlugin API, achieving complete separation between the core and extensions.
• Built-in Core Plugins: Provides the most commonly used developer plugins, LineNumbers and InsertMark, out of the box with no extra configuration needed.
• Modern Build: Packaged using tsup, providing ESM, CJS, and IIFE (browser) formats for each module (main library and plugins), perfectly adapting to any modern or traditional front-end project.
• Professional Development Experience: Full TypeScript support with precise type definitions.
• Extremely Lightweight: Inherits the core advantages of codejar, maintaining a minimal size and zero dependencies.

🚀 Installation

npm install codejarplus

Quick Start

1. In the Browser

This is the simplest way, suitable for static web pages or quick demos.

<div class="editor"></div>

<script src="https://unpkg.com/codejarplus/dist/iife/codejarplus.js"></script>
<script src="https://unpkg.com/codejarplus/dist/iife/plugins/lineNumbers.js"></script>

<script>
	const editor = document.querySelector('.editor');

	// Code highlighting function, you can use libraries like Prism.js
	const highlight = (editor) => {
		/* Your highlighting logic... */
	};

	const cjp = CJP.CodeJarPlus(editor, highlight, { tab: '\t' });

	// Register and enable the line numbers plugin
	cjp.addPlugin('lineNumbers', CJP.Plugin.LineNumbers, { show: true });

	cjp.updateCode(`function sayHello() {\n  console.log('Hello, CodeJarPlus!');\n}`);
</script>

2. In Modern Front-end Projects (e.g., Vite, Webpack)

import { CodeJarPlus } from 'codejarplus';
import { LineNumbers } from 'codejarplus/plugins';

const editor = document.querySelector('#editor');
const highlight = (editor) => {
	/* Your highlighting logic... */
};

const cjp = CodeJarPlus(editor, highlight, { tab: '\t' });

// Register and enable the line numbers plugin
cjp.addPlugin('lineNumbers', LineNumbers, { show: true });

cjp.updateCode(`function sayHello() {\n  console.log('Hello, CodeJarPlus!');\n}`);

Core API Details

Initializing CodeJarPlus(editor, highlight?, options?)

This is the entry function to create an editor instance.

• editor: HTMLElement: Required. The DOM element to be used as the editor.
• highlight?: (editor: HTMLElement) => void: Optional. A function for syntax highlighting. When the editor content is updated, this function will be called with the editor element as an argument. You can process editor.innerHTML inside this function to implement syntax highlighting.
• options?: Partial<Options>: Optional. A configuration object to customize the editor's behavior.

Configuration Options (Options)

• tab: string (default: '\t'): The string to insert when the Tab key is pressed.
• indentOn: RegExp (default: /[({\[]$/): A regular expression that triggers auto-indentation upon matching.
• moveToNewLine: RegExp (default: /^[)}\]]/): A regular expression that moves to a new line upon matching.
• spellcheck: boolean (default: false): Whether to enable spell checking.
• catchTab: boolean (default: true): Whether to capture the Tab key event.
• preserveIdent: boolean (default: true): Whether to preserve indentation on new lines.
• addClosing: boolean (default: true): Whether to automatically close brackets and quotes.
• history: boolean (default: true): Whether to enable undo/redo history.
• autoclose: object: Detailed configuration for the autoclosing feature.
• debounce: object: Debounce configuration, in milliseconds.
  • highlight: number (default: 300): Debounce delay for the highlight function.
  • update: number (default: 300): Debounce delay for the onUpdate callback.
• disableDebug: boolean (default: true): Whether to enable debugging. When enabled, it will print runtime logs to the console.

cjp Instance Properties and Methods

The CodeJarPlus(...) function returns an editor instance (which we'll call cjp), allowing you to fully control the editor.

Core Methods

• cjp.updateCode(code: string, callOnUpdate?: boolean): Programmatically updates the editor's code. callOnUpdate (default true) controls whether to trigger the onUpdate callback.
• cjp.onUpdate((code: string) => void): Registers a callback function that is triggered when the editor's code changes (with debouncing).
• cjp.toString(): string: Gets the plain text content of the editor.
• cjp.destroy(): Completely destroys the editor instance, removing all event listeners, plugins, and automatically created DOM elements to prevent memory leaks.

Cursor & History

• cjp.save(): Position: Saves the current cursor position and selection information, returning a Position object.
• cjp.restore(pos: Position): Restores the cursor position and selection based on a previously saved Position object.
• cjp.recordHistory(): Manually adds a snapshot to the history.

Plugin Management

• cjp.addPlugin(name, plugin, config?): Registers a plugin. Returns the plugin instance, through which you can call the plugin's specific APIs.
• cjp.removePlugin(name): Safely uninstalls a plugin by its name.
• cjp.updatePluginConfig(name, config): Updates the configuration of a registered plugin.
• cjp.destroyPlugins(): Destroys and removes all registered plugins.

Read-only Properties

• cjp.editor: HTMLElement: A reference to the original DOM element serving as the editor.
• cjp.id: string: The unique ID of the editor instance.
• cjp.options: Options: The currently effective configuration object.
• cjp.plugins: Map<string, IPlugin>: A Map object containing all registered plugin instances.

🔌 Plugin System

All extended functionalities of CodeJarPlus are implemented through plugins.

Using Built-in Plugins

CodeJarPlus provides a series of core plugins out of the box. >> Click here to view the detailed documentation for built-in plugins <<

Plugin Development

You can easily create your own plugins to extend the editor's functionality. A plugin is essentially a function that returns an object conforming to a specific interface.

Basic Structure of a Plugin

import { CodeJarPlus, IPlugin, ActionName } from 'codejarplus';

// Your plugin function
export function MyAwesomePlugin(cjp: CodeJarPlus, config?: MyPluginOptions) {
	// Plugin initialization logic...
	console.log('MyAwesomePlugin is initialized with config:', config);

	// Must return an object that conforms to the IPlugin interface
	return {
		// Core: onAction is the entry point for all editor events
		onAction: (params) => {
			const { name, code, event } = params;

			if (name === 'keyup') {
				console.log('User typed! New code length:', code.length);
			}

			if (name === 'keydown' && (event as KeyboardEvent).key === 'F1') {
				alert('F1 pressed!');
				return true; // Returning true can prevent the default behavior
			}
		},

		// Optional: Allows external updates to the plugin's configuration
		updateConfig: (newConfig: MyPluginOptions) => {
			console.log('Config updated:', newConfig);
			// ... Update the plugin's internal state
		},

		// Optional: Cleanup function, called when the plugin is removed
		destroy: () => {
			console.log('MyAwesomePlugin is destroyed!');
			// ... Remove event listeners, clean up DOM, etc., here
		},

		// You can also expose custom APIs
		myCustomMethod: () => {
			alert('Hello from MyAwesomePlugin!');
		}
	} as IPlugin<MyPluginOptions>;
}

The onAction Hook

This is the only channel through which plugins interact with the editor. The editor calls the onAction method of all registered plugins at various key points in its lifecycle.

The params argument of onAction includes:

• name: ActionName: The name of the currently triggered event.
• code: string: The current plain text content of the editor.
• event?: Event: The original DOM event object (if any).

Available ActionNames include:

• beforeUpdate
• afterUpdate
• keydown
• keyup
• focus
• blur
• paste
• cut
• scroll
• resize
• highlight

Acknowledgements

The creation of CodeJarPlus would not have been possible without the excellent foundation provided by antonmedv/codejar. Special thanks to the original author, Anton Medvedev, for his outstanding work and selfless contribution.

License

This project is licensed under the MIT License. Copyright is jointly held by WOODCOAL (木炭) and Anton Medvedev. See the LICENSE file for details.