# @wordpress/scripts és create-block

> A @wordpress/create-block egy parancsból létrehoz egy működő Gutenberg-blokk bővítményt, a @wordpress/scripts pedig lefordítja a forrást.

Gutenberg-blokkot modern JavaScripttel (JSX, ESNext) írsz, a böngésző viszont ezt közvetlenül nem futtatja. Két WordPress-csomag oldja meg a ráépülő munkát. A `@wordpress/create-block` létrehozza a bővítmény vázát, a `@wordpress/scripts` pedig a fordítást végzi. Neked nem kell webpacket, Babelt vagy ESLintet beállítanod.

## Mit kell hozzá telepíteni

- **Node.js.** A hivatalos fejlesztői környezeti útmutató az Active LTS verziót ajánlja, és egy verziókezelőt (például `nvm`) is. A `create-block` referenciája szerint legalább a `22.13.0` verzió kell.
- **Egy helyi WordPress.** A generált bővítményt kézzel kell a WordPress `plugins/` mappájába tenni, és aktiválni. A WordPress projekt a [wp-env](https://hub.hellowp.io/hu/knowledge-base/developer-tools/wp-env/) használatát ajánlja a Gutenberg-fejlesztéshez.

## Blokk létrehozása

A legrövidebb út, ha megadod a slugot:

```bash title="Terminál"
npx @wordpress/create-block@latest todo-list
cd todo-list
npm start
```

A slug lesz a mappa neve, a bővítmény neve és a blokk belső neve is. A többi beállítás alapértéket kap.

Slug nélkül interaktív módban indul, és megkérdezi a szükséges adatokat (slug, cím, névtér és társaik):

```bash title="Terminál"
npx @wordpress/create-block@latest
```

### Gyakori kapcsolók

| Kapcsoló | Mit csinál |
|---|---|
| `--namespace <érték>` | A blokk névtere. Alapértelmezetten `create-block`, a blokk neve `névtér/slug`. |
| `--title <érték>` | A blokk és a bővítmény megjelenő neve. |
| `--short-description <érték>` | Rövid leírás. |
| `--category <név>` | A blokk kategóriája. |
| `--textdomain <érték>` | A fordítások szövegtartománya. Alapértelmezetten a slug. |
| `--variant <név>` | A sablon egy változata. A `--variant dynamic` dinamikus blokkot ad. |
| `--template <név>` | A sablon: `standard` (alap), `es5`, npm-csomag neve vagy helyi mappa. |
| `--target-dir <mappa>` | A kimeneti mappa. Alapértelmezetten a slug. |
| `--no-plugin` | Csak a blokk fájljait hozza létre az aktuális mappába, bővítmény nélkül. |
| `--wp-scripts` / `--no-wp-scripts` | A `@wordpress/scripts` használatának be- és kikapcsolása. |
| `--wp-env` | `@wordpress/env` beállítást és hozzá egy szkriptet ad, a Dockerre épülő helyi WordPresshez. |

Például egyedi névtérrel és dinamikus blokkal:

```bash title="Terminál"
npx @wordpress/create-block@latest my-block --namespace=my-plugin --variant=dynamic
```

Ez a `my-plugin/my-block` nevű blokkot hozza létre. Ha később névteret cserélnél, írd át a `name` mezőt a `block.json` fájlban.

## A létrejövő mappaszerkezet

A Block Editor Handbook szerint a bővítmény így néz ki:

```text title="Mappaszerkezet"
todo-list/
├── todo-list.php     a bővítmény fő fájlja, itt van a blokk szerveroldali regisztrációja
├── package.json
├── src/
│   ├── block.json
│   ├── index.js
│   ├── edit.js
│   ├── save.js
│   ├── style.scss
│   ├── editor.scss
│   ├── render.php    csak dinamikus blokknál
│   └── view.js
└── build/            a src/ fordított kimenete
```

A fájlok szerepe:

- **`src/block.json`**: a blokk metaadatai (név, attribútumok, támogatások), és megmondja, mely fájlokat használja.
- **`src/index.js`**: a szerkesztő belépési pontja, itt hívódik a `registerBlockType`.
- **`src/edit.js`**: a blokk szerkesztőbeli felülete (React-komponens).
- **`src/save.js`**: a statikus HTML, ami az adatbázisba mentődik.
- **`src/style.scss`**: stílus a szerkesztőben és a nyilvános oldalon is.
- **`src/editor.scss`**: stílus csak a szerkesztőben.
- **`src/render.php`**: a dinamikus blokk kimenetét adja a nyilvános oldalon.
- **`src/view.js`**: a nyilvános oldalon betöltődő JavaScript.
- **`build/`**: a `wp-scripts` fordítja a `src/` tartalmából, és a WordPress ezeket a fájlokat tölti be.

## npm-szkriptek

A `create-block` ezeket a szkripteket írja a `package.json` fájlba, és `npm run <név>` paranccsal futtatod őket:

| Parancs | Mit csinál |
|---|---|
| `npm start` | Fejlesztői build figyelővel: a mentett változtatásra újrafordít, a hibákat a konzolban mutatja. |
| `npm run build` | Egyszeri, optimalizált éles build. |
| `npm run format` | Formázza a kódot. |
| `npm run lint:js` | JavaScript-ellenőrzés. |
| `npm run lint:css` | CSS-ellenőrzés. |
| `npm run packages-update` | Frissíti a `@wordpress/*` függőségeket. |
| `npm run plugin-zip` | Telepíthető bővítmény-zip készítése. |

A lint- és formázóparancsok hátteréről az [ESLint, Prettier és Stylelint](https://hub.hellowp.io/hu/knowledge-base/developer-tools/eslint-prettier-stylelint/) cikk szól.

Fejlesztés közben indítsd el az `npm start` parancsot, és hagyd futni. Telepítés vagy kiadás előtt futtass `npm run build` parancsot.

### Mit fordít a wp-scripts

A `build` és a `start` alapból a `src` mappában keres `block.json` fájlokat (almappákban is). A bennük megadott `editorScript`, `script` és `viewScript` JavaScript-fájlokból lesz belépési pont. Ha nincs `block.json`, a `src/index.js` (vagy `.jsx`, `.ts`, `.tsx`) az alap. A kimenet alapból a `build` mappába kerül.

Az `index.css` csak a szerkesztő stílusa, a `style-index.css` a nyilvános oldalé és a szerkesztőé is. A forrás- és kimeneti mappa a `--source-path` és `--output-path` kapcsolóval módosítható.

## A block.json szerepe

A `block.json` a blokk egyetlen leírása, amit a PHP és a JavaScript is olvas. A kézikönyv a blokkok regisztrálásának kanonikus módjaként ajánlja. Előnyei:

- a blokk eszközeit (szkript, stílus) csak akkor tölti be, ha a blokk szerepel az oldalon;
- a Block Directoryban megjelenő bővítmény minden blokkjához kell `block.json`;
- a séma fájllal a szerkesztő súgót, automatikus kiegészítést és ellenőrzést ad.

A fájlutak `file:` előtagot kapnak, és a `block.json`-hoz képest relatívak:

```json title="src/block.json"
{
	"apiVersion": 3,
	"name": "create-block/todo-list",
	"title": "Todo List",
	"textdomain": "todo-list",
	"editorScript": "file:./index.js",
	"render": "file:./render.php"
}
```

A `name` kötelező, `névtér/blokknév` alakban. A `render` (WordPress 6.1 óta) a dinamikus blokk PHP-fájlja. A fenti példa a mezők szemléltetésére rövidített, a generált fájl ennél több mezőt tartalmaz.

## Regisztráció PHP-ból

A blokkot a bővítmény fő PHP-fájljában, az `init` horogra kötve regisztrálod. A `register_block_type()` a `build` mappa `block.json` fájlját olvassa, nem a `src` mappáét:

```php title="todo-list.php"
function todo_list_register_block() {
    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'todo_list_register_block' );
```

Több blokkhoz a WordPress 6.8 óta a `wp_register_block_types_from_metadata_collection()` az ajánlott. Ehhez a `wp-scripts build-blocks-manifest` (vagy a build `--blocks-manifest` kapcsolója) egyetlen PHP-fájlba gyűjti a blokkok metaadatait:

```php title="todo-list.php"
function my_plugin_register_blocks() {
    wp_register_block_types_from_metadata_collection(
        __DIR__ . '/build',
        __DIR__ . '/build/blocks-manifest.php'
    );
}
add_action( 'init', 'my_plugin_register_blocks' );
```

## Mire figyelj

- A WordPress a `build` mappa fájlait tölti be, ezért a kiadott bővítménybe a fordított kimenetnek is be kell kerülnie. Az `npm run plugin-zip` zipbe csomagolja a bővítményt.
- Ha a témád vagy a teljes oldalad asseteit [Vite](https://hub.hellowp.io/hu/knowledge-base/developer-tools/vite/) építi, az a blokk-bővítménytől független: a blokk fordítását a `wp-scripts` végzi.

## Hasznos linkek

- [create-block referencia](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)
- [@wordpress/scripts referencia](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)
- [Get started with create-block](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/)
- [Block metadata (block.json)](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)
- [Registration of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals-block-development/registration-of-a-block/)
- [File structure of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals-block-development/file-structure-of-a-block/)