React-Ace Editor Component

Common errors

• Error: 'ace' is not defined

  cause The Ace Editor global object (`ace`) is not available because `ace-builds` has not been correctly imported or loaded.
  fix Ensure you have `ace-builds` installed and that the necessary `ace-builds` files are imported, particularly if you are trying to configure `ace.config.setOptions` or access other global Ace properties.

• TypeError: Cannot read properties of undefined (reading 'config')

  cause Attempting to access `ace.config` before the `ace-builds` library has initialized the `ace` global object.
  fix Make sure `import 'ace-builds';` or a specific mode/theme import that initializes the global `ace` object runs before any code attempting to access `ace.config` or similar properties.

• Warning: ace.config.set'setOptions' called before the editor is ready.

  cause Trying to apply editor options via `setOptions` prop or `ace.config.setOptions` too early, before the AceEditor component or the Ace library itself has fully initialized.
  fix For component-specific options, use the `setOptions` prop directly on the `AceEditor` component. For global Ace configurations, ensure `ace-builds` imports are at the top of your main entry file or explicitly manage their loading order.

Warnings

• breaking Version 8.0.0 of `react-ace` dropped support for `brace` and now directly depends on `ace-builds`. This requires updating your imports and potentially refactoring how modes, themes, and extensions are loaded.
  Fix: Remove `brace` from your dependencies. Install `ace-builds` (`npm install ace-builds`). Update all `import 'brace/mode/...'` statements to `import 'ace-builds/src-noconflict/mode/...'` and similar for themes and extensions. Refer to the 'Migrate to version 8' documentation.
• gotcha Modes, themes, and extensions for Ace Editor are not bundled with `react-ace`. They must be explicitly imported from `ace-builds` for the editor to function correctly with specific languages or visual styles.
  Fix: Ensure you `npm install ace-builds` alongside `react-ace`. Import necessary modes (e.g., `import 'ace-builds/src-noconflict/mode-javascript';`) and themes (e.g., `import 'ace-builds/src-noconflict/theme-github';`) at the top level of your application or before your AceEditor component renders.
• deprecated The `$blockScrolling` property within `editorProps` is a legacy setting from older Ace Editor versions. While still supported, it's often recommended to avoid it or address the underlying reasons for its use (e.g., complex layout issues) in modern React development, as it can sometimes lead to performance concerns or unexpected behavior.
  Fix: While often included in examples for compatibility, consider if `$blockScrolling: true` is truly necessary. For optimal performance and modern rendering, try to structure your CSS and components to avoid situations where `$blockScrolling` would be required. If you encounter issues, consult Ace Editor's documentation for alternatives.
• gotcha Updating `react-ace` to a new major version (e.g., v13 to v14) may introduce updated `peerDependencies` requirements for React itself, or updated `ace-builds` versions. Failing to update these alongside `react-ace` can lead to runtime errors or unexpected behavior.
  Fix: Always review the `peerDependencies` in `package.json` for `react-ace` and ensure your `react` and `react-dom` versions satisfy these requirements. Similarly, check the `ace-builds` version used by `react-ace` in its `package.json` to ensure compatibility, or update `ace-builds` if necessary.

Install

• npm install react-ace npm
• yarn add react-ace yarn
• pnpm add react-ace pnpm

Imports

• AceEditor
  wrong:

  import { AceEditor } from 'react-ace'; // Incorrect named import

  correct:

  import AceEditor from 'react-ace';

  AceEditor is a default export from the `react-ace` package.
• setOptions
  wrong:

  import { setOptions } from 'react-ace'; // Not directly exported by react-ace

  correct:

  import ace from 'ace-builds'; ace.config.setOptions({ useWorker: false });

  Configuration options for Ace Editor (like disabling workers or setting base path) are accessed via the `ace-builds` package's global `ace.config` object. Ensure `ace-builds` is imported or globally available.
• mode-javascript
  wrong:

  import { javascript } from 'ace-builds/src-noconflict/mode-javascript';

  correct:

  import 'ace-builds/src-noconflict/mode-javascript';

  Modes, themes, and extensions are imported for their side effects to register with the Ace Editor. They do not export symbols directly for consumption.

Quickstart

This quickstart demonstrates rendering a basic AceEditor component with JavaScript mode, GitHub theme, and essential extensions like language tools for autocompletion. It logs changes to the console and includes basic editor options for enhanced usability.

import React from "react";
import { createRoot } from "react-dom/client";
import AceEditor from "react-ace";

import "ace-builds/src-noconflict/mode-javascript";
import "ace-builds/src-noconflict/theme-github";
import "ace-builds/src-noconflict/ext-language_tools";

function MyAceEditor() {
  const onChange = (newValue) => {
    console.log("Editor content changed:", newValue);
  };

  return (
    <AceEditor
      mode="javascript"
      theme="github"
      onChange={onChange}
      name="code-editor-instance"
      editorProps={{ $blockScrolling: true }}
      setOptions={{
        enableBasicAutocompletion: true,
        enableLiveAutocompletion: true,
        enableSnippets: true,
        showLineNumbers: true,
        tabSize: 2,
      }}
      style={{
        width: '100%',
        height: '300px'
      }}
      placeholder="Start coding here..."
    />
  );
}

const container = document.getElementById('example');
if (container) {
  const root = createRoot(container);
  root.render(<MyAceEditor />);
} else {
  console.error("Root element 'example' not found.");
}