https://github.com/WebArtWork/ngx-ace-signal
https://github.com/WebArtWork/ngx-ace-signal
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/WebArtWork/ngx-ace-signal
- Owner: WebArtWork
- License: mit
- Created: 2025-12-11T15:03:24.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-03-21T07:41:36.000Z (3 months ago)
- Last Synced: 2026-03-21T21:34:47.396Z (3 months ago)
- Language: TypeScript
- Homepage: http://ace.webart.work/
- Size: 385 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- fucking-awesome-angular - ngx-ace-signal - A modern Angular signals-based wrapper for the Ace editor. (Third Party Components / Editors)
- awesome-angular - ngx-ace-signal - A modern Angular signals-based wrapper for the Ace editor. (Third Party Components / Editors)
README
# ngx-ace-signal
**ngx-ace-signal** is a modern Angular **signals-based** wrapper for the [Ace Editor](https://ace.c9.io/).
It is designed for **Angular 20+**, supports **SSR**, and avoids legacy patterns like `NgModule`, `@Input()`, or global side effects.
---
## Features
- ✅ Angular **signals** API (`input()`, `model()`, `output()`)
- ✅ **SSR-safe** − Ace is only loaded in the browser
- ✅ Dynamic **mode & theme loading**
- ✅ Component **and** directive APIs
- ✅ Fully typed config (`AceConfigInterface`)
- ✅ Works with standalone apps
---
## Demo
Example application (GitHub Pages):
👉 [https://ace.webart.work](https://ace.webart.work)
---
## Installation
```bash
npm install ngx-ace-signal
```
---
## Basic usage (component)
```html
```
```ts
code = `console.log("Hello Ace");`;
```
---
## Inputs (signals)
| Input | Type | Default | Description |
| ------------- | ---------------------------------- | ----------- | -------------------------------------- |
| `value` | `string` | `""` | Editor content (two-way via `model()`) |
| `mode` | `"text" \| "javascript" \| string` | `""` | Editor mode |
| `theme` | `"github" \| "clouds" \| string` | `""` | Editor theme |
| `disabled` | `boolean` | `false` | Disables editor |
| `readOnly` | `boolean` | `false` | Read-only mode |
| `config` | `AceConfigInterface` | `undefined` | Advanced Ace options |
| `useAceClass` | `boolean` | `true` | Toggles `.ace` host class |
---
## Outputs
```html
```
Supported events:
- `blur`
- `focus`
- `copy`
- `paste`
- `change`
- `changeCursor`
- `changeSession`
- `changeSelection`
---
## Directive usage (advanced)
```html
initial text
```
Access the editor API via template reference:
```html
```
```ts
editor.ace()?.setValue('Hello');
```
---
## Global configuration (optional)
Use `provideAce()` to define defaults once:
```ts
import { provideAce } from 'ngx-ace-signal';
bootstrapApplication(AppComponent, {
providers: [
provideAce({
showLineNumbers: true,
useWorker: false,
}),
],
});
```
---
## Dynamic mode & theme registration
You can extend supported modes/themes **without touching the library**:
```ts
import { registerAceMode, registerAceTheme } from 'ngx-ace-signal';
registerAceMode('json', () => import('ace-builds/src-noconflict/mode-json'));
registerAceTheme('monokai', () => import('ace-builds/src-noconflict/theme-monokai'));
```
Then use them normally:
```html
```
---
## SSR support
- Ace is **never imported on the server**
- All loading happens behind `isPlatformBrowser`
- Safe to use in Angular Universal / SSR apps
No special setup required.
---
## Configuration reference
All supported options are defined in:
```ts
AceConfigInterface;
```
This is a thin typed layer over Ace’s native configuration.
For full option details, see the official Ace documentation:
👉 [https://ace.c9.io/#nav-api](https://ace.c9.io/#nav-api)
---
## Notes on CommonJS warnings
`ace-builds` is CommonJS.
Consumer apps should add:
```json
"allowedCommonJsDependencies": ["ace-builds"]
```
This is expected and documented.
---
## AGENTS.md
Copy below code into AGENTS.md file of your project while you are using our plugin.
```md
## ngx-ace-signal
- This project uses `ngx-ace-signal`, an Angular 20+ Ace Editor wrapper built around signals and standalone APIs.
- Prefer importing `AceComponent` for `` usage or `AceDirective` for `[ace]` usage directly into standalone components instead of creating wrapper `NgModule`s.
- Use signal-style bindings that match the library API:
- Two-way content binding is `[(value)]`.
- Inputs include `[mode]`, `[theme]`, `[disabled]`, `[readOnly]`, and `[config]`.
- Outputs include `(change)`, `(focus)`, `(blur)`, `(copy)`, `(paste)`, `(changeCursor)`, `(changeSession)`, and `(changeSelection)`.
- When app-wide defaults are needed, configure them with `provideAce({...})` in application providers instead of duplicating editor config in many components.
- Do not import Ace directly in app code unless there is a documented reason. Prefer the library helpers `registerAceMode()` and `registerAceTheme()` to load extra modes/themes.
- If a feature needs a new mode or theme, register it explicitly, for example:
registerAceMode('json', () => import('ace-builds/src-noconflict/mode-json'));
registerAceTheme('monokai', () => import('ace-builds/src-noconflict/theme-monokai'));
- Keep SSR-safe behavior intact. Do not add server-side imports of `ace-builds`; the library already guards browser-only loading.
- If build tooling warns that `ace-builds` is CommonJS, allow it in Angular build config via `allowedCommonJsDependencies` rather than replacing the editor integration.
- When changing editor behavior, prefer passing options through `config` or `provideAce()` before modifying the library itself.
- If you need direct editor access, use a template ref with `#editor="ngxAce"` and then call `editor.ace()` rather than querying DOM globals.
```
## License
MIT © Web Art Work