# EditorJS to Blok Codemod

Automatically migrate your codebase from EditorJS to Blok.

## Installation & Usage

### Using npx (recommended)

The codemod is bundled with the `@bloklabs/core` package.

```bash
# Dry run (preview changes without modifying files)
npx -p @bloklabs/core migrate-from-editorjs ./src --dry-run

# Apply changes
npx -p @bloklabs/core migrate-from-editorjs ./src

# Process entire project
npx -p @bloklabs/core migrate-from-editorjs .

# Verbose output
npx -p @bloklabs/core migrate-from-editorjs ./src --verbose
```

### If you have @bloklabs/core installed locally

If you've already installed `@bloklabs/core` in your project, you can run the codemod directly:

```bash
npx migrate-from-editorjs ./src --dry-run
```

## What It Does

### Import Transformations

**EditorJS → Blok:**
```diff
- import EditorJS from '@editorjs/editorjs';
+ import { Blok } from '@bloklabs/core';

- import EditorJS, { EditorConfig } from '@editorjs/editorjs';
+ import { Blok, BlokConfig } from '@bloklabs/core';

- import Header from '@editorjs/header';
- import Paragraph from '@editorjs/paragraph';
- import List from '@editorjs/list';
+ import { Header, Paragraph, List } from '@bloklabs/core/tools';
```

**Blok default imports → named imports** (Blok only exports named exports):
```diff
- import Blok from '@bloklabs/core';
+ import { Blok } from '@bloklabs/core';

- import Editor from '@bloklabs/core';
+ import { Blok as Editor } from '@bloklabs/core';

- import Blok, { BlokConfig } from '@bloklabs/core';
+ import { Blok, BlokConfig } from '@bloklabs/core';
```

### Type Transformations

```diff
- import type { EditorConfig } from '@editorjs/editorjs';
+ import type { BlokConfig } from '@bloklabs/core';
```

### Class Name Transformations

```diff
- const editor = new EditorJS({ ... });
+ const editor = new Blok({ ... });
```

### CSS Selector Transformations

```diff
- .codex-editor { }
+ .blok-editor { }

- .ce-block { }
+ [data-blok-testid="block-wrapper"] { }

- .ce-block--selected { }
+ [data-blok-selected="true"] { }

- .ce-toolbar { }
+ [data-blok-testid="toolbar"] { }
```

### Data Attribute Transformations

```diff
- document.querySelector('[data-id="abc123"]');
+ document.querySelector('[data-blok-id="abc123"]');

- document.querySelector('[data-item-name="bold"]');
+ document.querySelector('[data-blok-item-name="bold"]');
```

### Default Holder Transformation

```diff
- <div id="editorjs"></div>
+ <div id="blok"></div>

- holder: 'editorjs'
+ holder: 'blok'
```

### Tool Configuration Transformations

The codemod converts old Blok static property references to direct imports:
```diff
tools: {
-   header: Blok.Header,
-   paragraph: Blok.Paragraph,
-   list: Blok.List,
+   header: Header,
+   paragraph: Paragraph,
+   list: List,
}
```

The codemod splits combined Blok imports into core and tools:
```diff
- import { Blok, Header, Paragraph, List } from '@bloklabs/core';
+ import { Blok } from '@bloklabs/core';
+ import { Header, Paragraph, List } from '@bloklabs/core/tools';
```

### package.json Updates

```diff
{
  "dependencies": {
-   "@editorjs/editorjs": "^2.28.0",
-   "@editorjs/header": "^2.8.0",
-   "@editorjs/paragraph": "^2.11.0",
-   "@editorjs/list": "^1.9.0",
+   "@bloklabs/core": "latest"
  }
}
```

## Options

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview changes without modifying files |
| `--verbose` | Show detailed output for each file |
| `--use-library-i18n` | Remove custom i18n messages and use Blok's built-in translations |
| `--help` | Show help message |

### Using `--use-library-i18n`

If your EditorJS project had custom translations, the codemod converts them to Blok's flat format by default. Blok also ships with built-in translations for 36 languages. To use those instead of maintaining your own, pass the `--use-library-i18n` flag:

```bash
npx -p @bloklabs/core migrate-from-editorjs ./src --use-library-i18n
```

This removes the `messages` property from your i18n config. Blok then auto-detects the user's locale from the browser and uses the matching built-in translations.

## Supported File Types

- JavaScript: `.js`, `.jsx`
- TypeScript: `.ts`, `.tsx`
- Vue: `.vue`
- Svelte: `.svelte`
- HTML: `.html`
- CSS: `.css`, `.scss`, `.less`

## After Migration

1. **Install dependencies**: Run `npm install` or `yarn` to update your dependencies

2. **Review changes**: The codemod handles most common patterns, but review the changes for:
   - Custom tool implementations
   - Complex selector patterns
   - Dynamic string construction

3. **Update custom tools**: If you have custom tools, ensure they follow Blok's API:
   - Lifecycle hooks: `rendered()`, `updated()`, `removed()`, `moved()`
   - Use `data-blok-*` attributes

4. **Test thoroughly**: Run your test suite and manually verify the editor works correctly

5. **Check MIGRATION.md**: See the full [migration guide](../MIGRATION.md) for manual updates

## Programmatic Usage

```javascript
// If you've cloned the blok repository
const {
  transformFile,
  updatePackageJson,
  applyTransforms,
} = require('./codemod/migrate-editorjs-to-blok');

// Transform a single file
const result = transformFile('/path/to/file.ts', false);
console.log(result.changes);

// Update package.json
const pkgResult = updatePackageJson('/path/to/package.json', false);
console.log(pkgResult.changes);
```

## Known Limitations

- Does not handle dynamic imports with variable paths
- Complex nested selectors may need manual adjustment
- Custom EditorJS plugins need manual migration
- String templates with EditorJS references need manual review

## Contributing

Found a pattern that should be transformed? Open an issue or PR on the [Blok repository](https://github.com/jackuait/blok).

## License

Apache-2.0