今回、社内でShopifyのアプリを作る機会がありました。Shopifyの公式にあるハンズオンを元にCLIでnodeアプリを作成しましたが、英語が苦手なこともあり、ところどころ詰まってしまいました。そこで、これからShopifyアプリを作ろうと思う方のためにまとめていこうと思います。

言ってしまえば、プラグインです。見た目のカスタマイズは主にテーマが担っています。アプリは管理画面の機能拡張やテーマへのパーツ追加などを行います。

<a href="https://shopify.dev/apps/getting-started" target="_blank">https://shopify.dev/apps/getting-started</a>

アプリには公開アプリとカスタムアプリの2種類が存在します。公開アプリは不特定多数のマーチャントが、Shopify アプリストア(url)からインストールすることが可能です。カスタムアプリは特定のマーチャントに対して公開する専用のアプリです。

アプリ開発時にどちらかを選択し、その後は変更することが出来ません。今回はカスタムアプリで説明をしていきます。

<a href="https://shopify.dev/apps/getting-started/app-types">https://shopify.dev/apps/getting-started/app-types</a>

node.jsまたはrailsを選択できます。今回はnode.jsで説明を進めていきます。

アプリはどのようにして動くのか、アプリはshopifyとは別に、アプリ制作者が用意したサーバーで動かします。Shopify側のサーバーからデータなどを取得し、自前のサーバーで処理や保持などを行い、Shopify側にデータを送る形になります。Shopifyの管理画面にアプリ独自のUIを追加する場合は、iframeで描画してます。

認証はOAuth2.0です。Store側でアプリのインストールをする際に、スコープ(各データへの必要なアクセス権)などを提示します。Store管理者が承認をすることで、アクセストークンが発行されアプリは要求したアクセス権を元に、データの取得や書き込みが出来るようになります。

APIキーやスコープなどはアプリの.envファイルに保持されます。

<a href="https://shopify.dev/apps/getting-started/app-types"></a><a href="https://www.shopify.jp/blog/partner-shopify-access-token-generate">https://www.shopify.jp/blog/partner-shopify-access-token-generate</a>

ではShopify アプリを実際に作ろうとしたらどのような手順になるのか。簡単な手順は以下のようになります。Shopify patnersの管理画面からも設定を作成することもできますが、エンジニアの方はCLIで完結できた方がやりやすいと思うので、その手順で説明します。

まずは開発を始めるためにshopify partnerのアカウントを作成します。shopify partnersのページ&nbsp;<a href="https://www.shopify.jp/partners">https://www.shopify.jp/partners</a>から新規登録を行います。

1つのパートナーアカウントで複数の開発ストアを立てられるので、1組織につき1parterアカウントでの作成になります。

パートナーアカウントにログインしダッシュボードが表示されたら、まずストアを作成します。ストア管理からストアの追加を選択してください。

まずはストアタイプは開発ストアを選択してください。ストアURLは<code class="inline-code">xxx.myshopify.com</code>という形式になりますが、一度設定したものは永久欠番になります。具体的には

なので、ドメインに組織名や開発環境であるような記述を含めると良いです。

開発者プレビューは、Shopifyの新機能をいち早く試せる機能です。互換性はあるので、アプリ開発をするのであればオンにしておいて損はないでしょう。

Shopify CLIはアプリ・テーマ開発を行うための便利な機能をCLI上から実行できるようにしてくれるツールです。

macでは以下のコマンドでインストールができます。

インストールが成功したら、<code class="inline-code">shopify help</code>で各コマンドの説明が見れます。

<a href="https://shopify.dev/apps/getting-started/create#step-1-install-shopify-cli">https://shopify.dev/apps/getting-started/create#step-1-install-shopify-cli</a>

今回はShopifyアプリがどのようなものか説明しました。また、アプリ開発の準備としてパートナーアカウントの作成、開発ストアの作成、Shopify CLIのインストールを行いました。

次回は実際にCLIを用いて、実際にアプリを動かしてみます。

Shopifyアプリの開発フローと準備

Shopify アプリことはじめ 2回目に当たる今回は、Shopify CLIを使ってローカル開発環境の立ち上げまでを行います。

前回記事より開発フローを再掲します。

今回は、「CLIで開発ストアへのログイン」から「ngrokでローカル開発環境を公開」までを行います。

CLIで開発ストアにログインする際、自身のメールアドレスで作成したアカウントでは開発ストアに対する各権限がない状態です。そこで開発ストア内にスタッフ登録を行い権限を与えます。

開発ストアの管理画面内左メニューの「設定」へ移動します。設定モーダルが開きますので、同モーダル左メニューの「ユーザーと権限」をクリックしてください。ユーザーと権限の設定画面が表示されましたら、スタッフ項目内の「スタッフを追加」をクリックしてください。

権限はすべてを選択し、アプリとチャネルも選択しておいてください。何か問題がある場合は、適宜権限を調整してください。

必要な項目を入力したら「招待を送信する」をクリックすることで入力したメールアドレス宛に、招待メールが送信されます。

メール内「Create staff acount」をクリックすれば登録完了です。

まずは、CLIでshopifyコマンドが実行可能か確認してください。

バージョンのみ表示されたら問題ありません。最新バージョンの案内をされた場合は適宜更新などを行なってください。

次いでCLIから開発ストアにログインします。

Storeオプションの値は開発ストアのドメインになります。テストするデータは指定した開発ストアのものを利用します。

また、複数開発ストアを用意しており、ログアウトをしたい場合は<code class="inline-code">shopify logout</code>でログアウトすることができます。

では実際にshopifyアプリを作っていきます。

Shopifyアプリに関するコマンドは全て<code class="inline-code">shopify app xxx</code>です。&nbsp;コマンドがわからなくなった場合は、<code class="inline-code">shopify app</code>で関連コマンドのhelpが確認できます。shopify cliのバージョンによってコマンドが違う場合があります。上手くいかない場合は<code class="inline-code">shopify help</code>で確認してください。

Nodeアプリをテンプレートから作成する場合は以下のコマンドを実行します。

作成が成功すると、指定したアプリ名と同名のディレクトリが出来ています。後の作業はこちらで行います。

作成時Nodeのバージョンが不適切だと、必要モジュールがインストール出来ない場合があります。その場合は指定のNodeのバージョンに合わせてから、npm iでモジュールをインストールし直してください。

ngrokのインストールと設定 (未設定の場合)

Shopifyアプリは、ストアからアプリ用のサーバーにhttpsで通信する必要があります。Shopify cliではngrokを利用してローカルホストをHTTPS対応の適当なドメインでトンネリングしてくれます。

Ngrokの設定をしていない場合は以下の手順で設定を行なってください。

ngrokのアカウントを作成します。ngrokのページにいきSign upを行ってください。

登録が完了したら、管理画面のサイドメニューから「Your Authtoken」を選択し、トークンをコピーしてください。トークンはngrokインストール後に利用します。

CLIに戻ります。以下のコマンドでngrokのインストールを行ってください。（Macのパッケージ名が3つ連なっているのは記述ミスではありません。）

インストールが成功したら、下記のコマンドで先ほどコピーしたトークンを登録してください。

ngrokでローカル開発環境を公開

まだアプリには何も手を入れていない状態ですが、動作確認のためにローカルサーバーを立ち上げます。

こちらのコマンドで、アプリケーションの開発モードでの起動(next dev)とローカルホストのトンネリング(ngrok http)を良しなに実行してくれます。

先述の開発ストアの選択とアプリ名の指定を行なっていると、.envファイルに環境変数が設定されます。こちらが存在しない場合は、対話形式で開発ストアとアプリ名を選択することになります。

Running server...の記述内でエラーが出ている場合は、「指定されたポートが別プロセスで使われている」、「ngrokを別のプロジェクトで使用し、制限がかかっている」などの理由が考えられます。ポートは<code class="inline-code">Shopify app serve —port={ポート番号}</code>で指定可能です。 ngrokで制限がかかっている場合は、ngrokのプランを変更するか、使用していないngrokのプロセスを止めてください。

ここまで上手く行きましたら、<code class="inline-code">To install and start using your app, open this URL in your browser:</code>で指定されているURLにブラウザからアクセスしてください。

指定した開発ストアでアプリをインストールするかの確認が表示されます。

アプリのインストールをクリックしてください。上手くいくと、一時的にトンネリングしたurlでアプリが表示された後、開発ストアが表示されます。

開発ストア内で以下のようなコンテンツが表示されていれば成功です。

<code class="inline-code">Ctrl+C</code>でプロセスを終了します。この時、ngrokのプロセスが生きていたことがありました。何か別件で問題があった場合はngrokのプロセスが残っていないか確認をしてください。

Shopify cliを利用してNodeアプリのローカル開発環境の立ち上げまでを行いました。次回はShopifyのReact UIコンポーネント集 Polarisを使って、独自の管理画面を作り上げていきます。

CLIでShopifyアプリの開発環境を用意する

Shopify アプリことはじめ 3回目に当たる今回は、実際にアプリの開発作業に入っていきます。

開発の項目に関しては、ShopifyのUIライブラリであるPolarisによる管理画面の作り方と、Shopify GraphQLを利用したリソースの管理に分割してご紹介していきます。

本シリーズでは「指定タグのついた注文情報を発送済にする」アプリを作っていきます。<a href="https://shopify.dev/apps/getting-started/add-functionality" target="_blank">Shopifyの一番最初のハンズオン</a>は商品の価格を変更するアプリです。なのでせっかくですので別のリソースを使ったアプリをサンプルにします。

まずはGraphQLを利用したリソース管理から紹介したいのですが、今回はその準備としてリファレンスやツールの紹介とテストデータの準備を行います。

ShopifyはいくつかのAPIを有しておりますが、商品情報や注文情報を管理したい場合はAdmin APIを利用します。Admin APIはインターフェイスとしてGraphQLとRESTの二つが用意されています。

本シリーズではGraphQLを使ってアプリを作ります。なぜなら、そちらの方が楽しいからです。

RESTの方が好みだという方もいらっしゃると思います。そのような方でも追いやすいように、RESTではどこのリファレンスを参照すれば良いかをご紹介し、GraphQL同様に進めていけるようにします。

リソース取得に使うquery、リソースの追加・更新・削除などに使うmutation、そしてそれぞれで扱われるobjectに関しての説明はこちらで確認できます。

<a href="https://shopify.dev/api/admin-graphql" target="_blank">https://shopify.dev/api/admin-graphql</a>

RESTの場合はこちらを参照してください。GraphQLを使用している場合でも一部のfilterなどで使える値をこちらで確認するケースもありました。

<a href="https://shopify.dev/api/admin-rest" target="_blank">https://shopify.dev/api/admin-rest</a>

queryやmutationのテストが行えます。

<a href="https://shopify.dev/apps/tools/graphiql-admin-api" target="_blank">https://shopify.dev/apps/tools/graphiql-admin-api</a>

Explorerタブをクリックすると、左側にGraphQLクエリの一覧が表示されます。使用したいGraphQLクエリ、レスポンスに欲しい値をなどをクリックしていくことで、GraphQLクエリを作成してくれます。

mediaLibraryStrapi

PreviewタブをクリックすることでGraphQLクエリの整形もしてくれます。完成したら再生ボタンを押すことで、サンプルのレスポンスを確認することが出来ます。何かミスがあればエラーも確認することが出来ます。

ストアスタッフが取得したいタグを複数入力すると、条件に合った注文の一覧が表示されます。「発送済にする」ボタンをクリックすると、対象の注文が逐次発送済ステータスになります。

上記の要件から以下の2点が必要だと考えられます。

注文検索時に1を実行し注文一覧を取得、ボタンクリックで2を実行し対象の注文を発送済ステータスに変更するという流れです。

GraphQL Admin APIを触る前に、下準備をしておきましょう。

ShopifyではCLIを通して、複数のテストデータを作成することが出来ます。では注文を作成していきます。

shopify populateは指定したリソースを作成するコマンドです。正確には注文を直接作成することはできないので、注文の下書き(draftorder)を作ります。他にも商品(product)や顧客(customer)のデータを作ることが出来ます。

nオプションは作成するリソースの件数です。未指定の場合は5件作成されます。

作成した注文の下書きは、ストア管理画面の「注文管理」→「下書き」から確認できます。このままではテスト出来ないので、支払いを回収し注文に変換していきます。CLIから変更はできないので、ストア管理画面から対象の注文の下書きを選択し、GUIで変更していきます。

詳細画面の「支払いを回収」ボタンをクリックし、「支払い済みとしてマークする」を選択してください

確認用のモーダルが表示されますので、そのまま「注文を作成」ボタンをクリックすると、注文が作成されます。

次に作成するアプリがストア内のリソースを操作できるように、スコープを指定します。スコープを指定することで、アプリインストール時にストアスタッフに指定スコープを承認するかの確認が表示されるようになります。

今回必要となるスコープは以下です。

ルートディレクトリ直下にある<code class="inline-code">.env</code>に必要なスコープを,繋ぎで記述してください。

既にアプリがインストールされていた場合でもスコープが更新されると、アプリ表示時に再度確認画面が表示されます。ストアの管理画面から作成中のアプリに移動し、承認を行なってください。

作成するアプリにどのようなスコープが必要か確認したい場合は、リファレンスを参照します。必要スコープの記述は各mutationやobjectの仕様ページにあります。

例えば今回は、orderオブジェクトを取得するので、以下のページで確認します。

<a href="https://shopify.dev/api/admin-graphql/2022-04/objects/Order#top" target="_blank">https://shopify.dev/api/admin-graphql/2022-04/objects/Order#top</a>

RESTの場合は各リソースの使用ページにCautionの形で記述されています。

<a href="https://shopify.dev/api/admin-rest/2022-04/resources/order#top" target="_blank">https://shopify.dev/api/admin-rest/2022-04/resources/order#top</a>

長くなってしまいましたので、今回は一旦ここまでとします。GraphQLを利用するのに必要なリファレンス・ツールの紹介をしました。また、開発時に使用するテストデータの作成と、アプリのスコープの設定を行いました。

次回はApollo Clientを用いてGraphQLでShopifyのリソースを管理する方法を紹介します。

Shopify アプリ開発(GraphQL準備編)

Shopifyアプリをnodeで作成していくシリーズ

Shopifyアプリことはじめ

レポジトリ運用において、変更が承認されマージされたらサーバーにデプロイされる仕組みは既に多くの方が取り入れていると思います。 しかし、マージ前（＝プルリクエスト）の状態でそのコードを反映したアプリケーションをサーバーに上げられると、確認環境として共有したり数パターンの変更を並べて見ることができたりと便利です。本記事では、Dokkuを用いたプルリクエスト連動CI環境の作成を紹介します。 Dokkuとは、アプリケーションのデプロイ環境を手軽に作成できるPlatform as a Service (PaaS)です。オープンソースであり、無料で利用できます。DokkuとGithub Actionsと合わせることで比較的簡単にこのCI環境を作成できます。 公式サイト Dokku&nbsp;<a href="https://dokku.com/docs/getting-started/installation/" target="_blank">https://dokku.com/docs/getting-started/installation/</a> Github Actions&nbsp;<a href="https://docs.github.com/ja/actions" target="_blank">https://docs.github.com/ja/actions</a>

Dokkuをインストールするためのサーバーを起動します。 本記事ではAWS EC2インスタンスを使います。GCP等別のサービスを使う場合は適宜読み替えてください。

Dokkuのドキュメント上の要求スペックは1GB RAMと書かれていますが、アプリケーションコンテナを複数起動するので実際はもっと多いほうがいいです。アプリケーションやチームの大きさ・利用頻度に合わせて変更してください。 またDockerはストレージを結構使うので、追加のストレージが必要になります。利用頻度にもよりますが、128GBくらいはあった方がいいと思います。（ちなみに当社では t3.large + 128GB です）

Dokkuをホストするサーバー用にドメインを用意します。持っていない場合はお名前.com、Route53などのDNSサービスで取得してください。 更に、今回のDokku用のサブドメインを作成します。管理画面から、先ほど起動したサーバーのIPアドレス宛に <code class="inline-code">dokku.yourdomain.com</code>, <code class="inline-code">*.dokku.yourdomain.com</code>&nbsp;（以下、サンプルではこのドメインで進めます）のAレコードを作成します。

まずは公式ドキュメントに沿ってインストールを進めます。（　<a href="https://dokku.com/docs/getting-started/installation/#getting-started-with-dokku" target="_blank">https://dokku.com/docs/getting-started/installation/#getting-started-with-dokku</a>　） インスタンスにSSHでログインした後、Dokkuをインストールします。

次に、ローカルでデプロイするサンプルのアプリを作成します。 サンプルとしては create-next-app （&nbsp;<a href="https://nextjs.org/docs/getting-started" target="_blank">https://nextjs.org/docs/getting-started</a> ）等で構いません。が、ちゃんとしたアプリがあればそちらを使ってもいいです。 作成したら、githubにもレポジトリを作ってこのアプリケーションをプッシュしておきます。

他にもいくつか方法がありますが、今回は基本となる「サーバー上にクローンしたレポジトリに変更をプッシュする方法」でdokkuサーバーにデプロイします。後ほどGithub Actionsの設定を行いますが、試しにmainブランチを手動デプロイしてみます。

pushのログが⇡ のように出れば成功です。 <code class="inline-code">http://&lt;レポジトリ名&gt;.dokku.yourdomain.com</code> にアクセスするとサンプルアプリのホーム画面が出ているはずです。

そのままだとhttpなので、Let's EncryptでSSL化します。 Dokkuがdokku-letsencryptというプラグインを用意しています。ワイルドカードが未サポートの様ですが（issueの投稿によればサポートする可能性はあるようです）、自動でやってはくれるので、少々汚いですがブランチごとにこのプラグインで取り直す形を取ります。 （別で取得した場合は certs:add します。詳しくは <a href="https://dokku.com/docs/deployment/application-deployment/#setting-up-ssl" target="_blank">https://dokku.com/docs/deployment/application-deployment/#setting-up-ssl</a> ）

改めて&nbsp; <code class="inline-code">https://&lt;レポジトリ名&gt;.dokku.yourdomain.com</code>&nbsp;にアクセスして、鍵マークが付いていれば完了です。 後編ではGithub Actionsとの連携を設定します。

Dokku + Github Actions でプルリクエストに連動したサーバーを立てる　前編

前編はこちら: <a href="http://https;//techlab.q-co.jp/articles/51/" target="_blank">https;//techlab.q-co.jp/articles/51/</a> Webエンジニアの茄子です。 前編では、dokkuのインストールからアプリケーションをデプロイするところまで行いました。 本記事ではデプロイをGithub Actionsで行う設定を紹介します。

dokkuのガイドではアプリケーション(app)は１レポジトリ１コンテナの対応で、`dokku git:set` によってそのデプロイ対象ブランチを切り替えるという想定のセットアップになっていました。 ここから主目的である、すべて同じアプリケーションで違うブランチという構成に設定していきます。 まずは、いくつかの下準備をします。

Dockerのディレクトリを外部ボリュームに移動

Dockerはイメージなどで容量が必要なので元の8GBでは足りなくなります。そのためDockerの使うディレクトリを外部ボリュームに移動させます。 下記リンクのチュートリアルに従って移動してください。サービスやOSが違う場合は適宜読み替えてください。 チュートリアル:&nbsp; <a href="https://dokku.com/docs/community/tutorials/run-on-external-volume/" target="_blank">https://dokku.com/docs/community/tutorials/run-on-external-volume/</a> AWS Docs:&nbsp; <a href="https://docs.aws.amazon.com/ja_jp/AWSEC2/latest/UserGuide/ebs-using-volumes.html" target="_blank">https://docs.aws.amazon.com/ja_jp/AWSEC2/latest/UserGuide/ebs-using-volumes.html</a>

使っていくと不要になったイメージなどがどんどん溜まっていくので、削除するcronをあらかじめ設定しておきます。

Github Actionsの処理の中でSSHキーが必要になります。 レポジトリの Settings -&gt; Secrets -&gt; Github Actions を開き、インスタンスにログインするものと同じプライベートキーを登録してください。インスタンス作成時と別のものを使う場合はインスタンスへの登録に加えて、dokkuへの登録も改めて必要になります。

また、インスタンスのファイアウォールが有効な場合、Github ActionsからDokkuサーバーへのアクセスを許可する必要があります。 <a href="https://docs.github.com/ja/rest/meta#get-github-meta-information" target="_blank">https://docs.github.com/ja/rest/meta#get-github-meta-information</a>&nbsp;から使われる可能性のあるIPアドレスのリストを取得できます。大量なので少し時間がかかるかもしれません。

本題のPRごとにする設定をします。 <a href="https://github.com/dokku/github-action/blob/master/example-workflows/review-app.yml" target="_blank">https://github.com/dokku/github-action/blob/master/example-workflows/review-app.yml</a> dokkuが用意している Github ActionsプラグインにPreview App というPR向けの機能が用意されているのでこちらを元に設定します。

アプリケーションのルートに .github/workflows/pull_request.yaml を作成します（ファイル名は任意） ドメイン、鍵の名前等を適宜自身の環境に合わせて変更してください。 以下に示す設定では、コンテナはGithubのPR番号をとって、pr-1, pr-2 のような名前で作成されます。( ＝サイトは https://pr-1.dokku.yourdomain.com ) review_app_name: pr-${{ github.event.pull_request.number }} で任意に変更可能です。（変更した場合、SSHで domains:set をする場所も変更してください。）

目的はPR用のサーバーですが、メインのブランチも一緒に運用していく場合はプッシュ用のActionも作ります。 .github/workflows/push-main.yaml

・新しいブランチを作って適当な変更を加えてプッシュし、プルリクエストを作ってサーバーが起動する ・更に適当な変更を加えてプッシュし、変更点が反映される ・プルリクエストをマージしmainのサーバーが更新される（push-mainを作った場合）

以上を確認できたら、完成です。

Dokku + Github Actions でプルリクエストに連動したサーバーを立てる　後編

プルリクエストに連動したCI/CDサーバーを立てる例です。

Dokku + Github Actions でプルリクエストに連動したサーバーを立てる

こんにちは、エンジニアチームのさらだです。

簡単な装飾をおこなったコンテンツをGUI上で入力できるリッチテキストエディター。
Wordpressでも利用されているGutenbergなどが有名ですね。

リッチテキストエディターは数あれど、 「この装飾がない！」 「出力をカスタマイズしたいからjson形式で取り出したい！」 「エディター内とフロントアプリケーションのスタイルを合わせたい！」 など、既製ライブラリままだと要件を満たせないこともあると思います。

そこで、今回はMetaのリッチテキストエディターを作れるフレームワーク、Lexicalの使い方を紹介します。 LexicalはReact用のインターフェイスも用意してくれているので、今回はReactでの使い方になります。

TypeScript 4.8.4 React 18.0.0 Lexical 0.5.0

<a href="https://lexical.dev/">Lexical</a>は前述の通り、リッチテキストエディターを作るフレームワークです。 見た目の作成は担当せず、入力中のコンテンツと何が選択されているかなどをエディターの状態とし、この状態を管理するための様々な機能を提供してくれます。

コアとなるlexical自体には汎用的な管理機能しか提供されていません。 Undo,Redoといった履歴機能や、リスト表示といったDOM変更機能など、特化した機能はサブパッケージとして利用することが出来ます。

Lexicalを用いてリッチテキストエディターを作ると

といった流れになります。 ここからはLexicalのコンセプトをいくつかピックアップして紹介します。

Lexialはコンテンツの入力内容や、選択状態などをエディターの状態としてEditor Stateで管理しています。

[<a href="https://lexical.dev/docs/concepts/editor-state">Editor State</a>]

Editorにあらかじめ用意したCommandを登録し、dispatchで呼び出すことが出来ます。

Editor Stateの更新などの各種イベントの発生時に実行したい関数を登録することが出来ます。各イベントへの登録は<code class="inline-code">EditorState.registerXXX()</code>で行います。

[<a href="https://lexical.dev/docs/concepts/listeners">Listener</a>]

コンテンツの入力内容を表現するモデルです。 <code class="inline-code">LexicalNode</code>を基底クラスとして、<code class="inline-code">RootNode</code>、<code class="inline-code">TextNode</code>、<code class="inline-code">ElementNode</code>などでコンテンツを表現します。

Editor Stateにはコンテンツの入力内容が<code class="inline-code">RootNode</code>を根としたNodeツリーで保存されます。

[<a href="https://lexical.dev/docs/concepts/nodes">Node</a>]

エディターの選択状態です。コンテンツの入力内容を示すツリー内のどのNodeを選択しているかを示します。

いくつかSelectionの種類がありますが、汎的なRangeSelectionではよく<code class="inline-code">anchor</code>と<code class="inline-code">focus</code>という値を利用します。 <code class="inline-code">anchor</code>は選択したコンテンツ内の先端を、<code class="inline-code">focus</code>は末端の位置を示します。

[<a href="https://lexical.dev/docs/concepts/selection">Selection</a>]

他にもLexicalの根幹をなすコンセプトはありますが、本記事内の紹介でよく使うものだけをピックアップしました。 それでは実際に実装していきます。

TypeScriptやreactは既に準備されている前提です。 ここからは公式のデモであるplaygroundを参考に、

という章立てで進めていきます。 本記事では既存のプラグインを利用した見た目の変更までをご紹介します。 残りの3つに関しては後編でご紹介します。

Editorの本体です。重要な部分をフィーチャーしていきます。

Providerの役割を果たします。この配下でEditorのContextを利用することができます。 自作プラグインを含めた各種プラグインは、子コンポーネントとして指定してください。

<code class="inline-code">initialConfig</code>はEditorの初期設定で必須項目です。 いくつかパラメータがありますが、以下の2つが必須項目になっています。

所謂リッチテキストを提供するプラグインです。 タイトル表記やリスト表記などを行うのに必要です。

<code class="inline-code">contentEditable</code>は実際にコンテンツ入力を行うComponentを指定します。 既製のContentEditable Componentを指定していますが、このComponentのPropsだけでも色々と設定できます。

<code class="inline-code">placeHolder</code>はそのままプレースホルーダーを設定できます。型はJSX.elementなのでDOMやReactNodeなども指定できます。

プレーンなテキストのみを扱うのであれば<code class="inline-code">PlainTextPlugin</code>もあり、同様のインターフェイスで実装できます。 プレーンなエディターを作ると銘打っていますが、後のお話で置き換えることになるので、こちらでは<code class="inline-code">RichTextPlugin</code>を利用しています。

Editorに変更があった際のコールバック関数を指定するプラグインです。 <code class="inline-code">onChange</code>でコールバック関数を指定します。

これがなくてもEditorは更新されるため動作しますが、実際に使用する場合はComponentの外部とのやりとりが必要なので、利用します。

スタイルの変更などを行うツールバーを用意していきます。 Editor Stateに含まれるSelectionで指定されたNode、つまり選択中のNodeを指定のNodeに変換するボタンを用意していきます。

ボタンの状態は選択されたNodeの状態を見て、アクティブか非アクティブかを表示します。 なので、ツールバーにも状態があることになります。

<a href="https://playground.lexical.dev/">Playground</a>ではツールバー内で状態を持っていますが、他のツールバーと共通の状態にしたいので今回はツールバー内の状態をContextで用意していきます。

まだ特に何も値を用意していない状態です。

<code class="inline-code">LexicalComposer</code>内で、Editor Stateを参照するためのHookです。 ツールバーの状態の更新するためにEditor Stateを参照します。

こちらにEditor State更新後に行いたい処理を書いていきます。

<code class="inline-code">$getSelection</code>など<code class="inline-code">$</code>から始まる関数は<code class="inline-code">EditorState.update()、</code><code class="inline-code">EditorState.read()</code>などの特定のスコープでのみ実行できるLexicalの特殊な関数です。 ReactでいうHookみたいなものを想像してくれと、公式では言及されています。 こちらの関数は、後述の<code class="inline-code">EditorState.read()</code>内で実行するので、この特殊関数を実行できます。

<code class="inline-code">$getSelection</code>で<code class="inline-code">EditorState</code>内のSelectionを取得を、<code class="inline-code">$isRangeSelection</code>でそのSelectionが、RangeSelectionと呼ばれる一番汎的な選択タイプかを判定を行なっています。

Editor Stateのリスナーの一つで、<code class="inline-code">EditorState</code>の状態が更新された時に実行したい処理を関数として登録できます。 こちらのコールバック関数内で、<code class="inline-code">EventState.read()</code>を呼び、その中でツールバーの更新処理を行っております。

なぜ<code class="inline-code">EventState.read()</code>を利用する必要があるのか。 これは、LexicalがEditorStateの更新にダブルバッファリングを採用しているためです。 現在の状態と、変更後の未来の状態を保有しているため、各イベントフック内で正確な状態を参照するため、<code class="inline-code">EventState.read()</code>を利用しております。

こちらがツールバーの表示部分になります。 まだ何もありません。

リストなどの見た目を変更するボタンを作る(既存のプラグインを利用する)

ツールバーに機能を足していきます。 最初の例はリストです。 リストに関しては、既存のListPluginとCheckListPluginで作れるので最初の例として採用しました。

必要なプラグインなどを読み込む

<code class="inline-code">ListPlugin</code>はul、olといった順序なしリスト、順序ありリストをサポートするプラグインです。 <code class="inline-code">CheckListPlugin</code>を入れることで、チェックリストも対応できます。

この二つのプラグインを利用するには、対応するNodeを読み込み、Editorに認識してもらう必要があります。 そのため、<code class="inline-code">initialConfig</code>の<code class="inline-code">nodes</code>パラメータに必要なNodeを指定しています。

Context側では、クリックした際に対応したリストに変更される関数<code class="inline-code">toggleXXX()</code>を用意します。後々ボタンに状態がつくと、解除もできるようになるのでtoggleとつけておきます。

<code class="inline-code">LexicalEditor.dispatchCommand()</code>で、SelectionのNodeを変更するCommandを実行します。

<code class="inline-code">INSERT_UNORDERED_LIST_COMMAND</code>などのCommandは、各プラグイン内で既にEditorに登録されています。 そのため、プラグイインからインポートし<code class="inline-code">LexicalEditor.dispatchCommand()</code>で実行するだけで済みます。

<code class="inline-code">LexicalEditor.dispatchCommand()</code>の第2引数には、Commandに渡す値を指定できますが、今回利用するCommandでは不要なため<code class="inline-code">undefined</code>になります。

Component側はシンプルで、Contextで定義した関数をクリック時に実行してあげるだけです。

これで選択中のコンテンツが、ボタンをクリックすることで対応のリスト表記に変更されるようになりました。 (チェックリストに関してはこの時点では見た目は変わりません。DOMを見てみるとliタグに<code class="inline-code">role="checkbox"</code>が付与されていることが確認できます。)

しかし今のままだと一度リスト表記にしてしまったら、元に戻せなくなってしまいます。 また、選択中のコンテンツにどのスタイルが当たっているのかが一見して分けって欲しいところです。

ということでボタンに状態を持たせて、ちゃんと表記のリセットも行えるようにしてきます。

現在選択しているNodeがどのようなブロック要素なのかを示すため、<code class="inline-code">useState</code>で<code class="inline-code">blockType</code>を用意します。 <code class="inline-code">blockType</code>が取り得る値は<code class="inline-code">BLOCK_TYPES</code>で定数化しています。<code class="inline-code">bullet</code>、<code class="inline-code">number</code>などの値は実際にNodeから取得できる値になります。

<code class="inline-code">getSecondRootNode()</code>は指定Nodeの親を辿り、<code class="inline-code">RootNode</code>を除いた最上位のNodeを取得する関数です。<code class="inline-code">$findMatchingParent</code>で条件を満たす限り、先祖Nodeを探索していきます。 この関数は後に選択中のNodeの中で最上位のものがどのような状態なのかを確認するために使用します。

<code class="inline-code">RangeSelection.anchor.getNode()</code>で、選択範囲内の先端のNodeを取得します。ここから先述の<code class="inline-code">getSecondRootNode()</code>を利用し、<code class="inline-code">RootNode</code>を除いた最上位のNodeを取得します。

<code class="inline-code">$isListNode</code>でこちらのNodeが<code class="inline-code">ListNode</code>であるかを判定します。 これは、<code class="inline-code">ListNode</code>と他のNodeでブロックの種類を取得する方法が異なるために行います。

Lexicalでリッチテキストエディターのベースを作る

<a href="/articles/66/">前編</a>に続き、Lexicalについてのご紹介です。 前回はLexicalのコンセプトに触れつつ、リスト表記を切り替えるツールバーを用意するところまで行いました。

後編ではLexical既存のプラグインだけでは実装できない機能をカスタムプラグインという形で実装したり、見た目やデータの取り扱いなど実際にプロジェクトで利用できるところまでやっていきます。

前編で完成したコードから作業を進めます。 後編から進める方は、こちらのコードを参考にしてください。

既存のNodeに手を加えるプラグインや、UIを提供するプラグインなど カスタムプラグインを作ろうとすると色々な種類が考えられます。

本記事では、なるべく出来ることが増えるように自作のNodeを追加するプラグインについて解説していきます。

自作Nodeを追加するにはいくつか用意するものがあります。

プラグイン本体はReact Componentとして作成します。 Componentにすることで、<code class="inline-code">LexicalComposer</code>の子コンポーネントとして指定することで、機能を追加することが出来ます。

内容としては、<code class="inline-code">LexicalEditor</code>に変更があった際に、あらかじめ作成したカスタムコマンドを<code class="inline-code">LexicalEditor.registerCommand()</code>で登録しておくだけになります。

今回のプラグインはUIを提供しないため、返り値は<code class="inline-code">null</code>になります。

追加したいDOMをNodeとして宣言します。 基本的には<code class="inline-code">LexicalNode</code>、または<code class="inline-code">LexicalNode</code>を基底とした既存のNode(<code class="inline-code">ElementNode</code>、<code class="inline-code">TextNode</code>、<code class="inline-code">DecoratorNode</code>)を継承して自作のNodeを作成します。

いくつかオーバーライドすべきメンバー関数があります。 上記のサンプルでは共通で最低限必須であろうメンバー関数をピックアップしています。

<code class="inline-code">getType()</code>はNodeの型名の取得に利用します。前編では<code class="inline-code">LexicalNode.getType()</code>が<code class="inline-code">'root'</code>であるかの判定を行なっていました。

Lexicalで自作プラグインを作りリッチテキストエディターをカスタマイズする

Metaのリッチテキストエディターを作れるフレームワーク、Lexicalの使い方を紹介します。