elisp-nextmain

elisp-next

elisp-react のための「ファイルがページになる」層です。React と Next.js の中間の書き心地を Emacs Lisp で実現します。

English · 使用例: Parens(YouTube 風の動画ブラウザ、公開中)

Next.jselisp-next
ページapp/watch/page.js がコンポーネントを exportpages/watch.el に (nextel-page WatchPage ...)
そのアドレスファイルのパスファイルのパス: pages/channel/[id].el は /channel/ID
全ページを囲むものlayout.jspages/_layout.el、(nextel-layout Layout ...)
見つからないときnot-found.jspages/404.el
ページのデータサーバーコンポーネント:load(nextel-request などの awaitable)。待つ間は :loading、失敗は :error
タイトルと metagenerateMetadata:head
リンク<Link href>(Link (:href (nextel-href "/watch" :v id)) ...)
APIapp/api/later/route.js が GET、POST を exportapi/later.el に (nextel-handle "GET" ...)、(nextel-handle "POST" ...)
共有する型TypeScript の型nextel-defschema。両側で実行時に検査
ルートの発見開発サーバーが app/ を監視Emacs が routes.el と <script> タグを書く(M-x nextel-write-routes、または保存のたびに)

Lisp の接頭辞は nextel- です。next- は Emacs 自身のもの(next-line、next-match)だからです。

完全な API は、コーディングエージェントが推測せずに使えるように書いた doc/api.md(英語)にあります。日本語訳は doc/api.ja.md で、Web ページ版は https://modeverv.github.io/elisp-next/api/ja/ です(英語版は https://modeverv.github.io/elisp-next/api/)。食い違うときは英語版が正しいものとします。 SKILL.md は、エージェントにそれを読んで実装するよう指示する Agent Skill です。このリポジトリを skills のディレクトリに clone して使います(Claude Code なら ~/.claude/skills/elisp-next、プロジェクトごとなら .claude/skills/elisp-next)。

プロジェクトで使う#

プロジェクトは elisp-next のコピーを vendor/elisp-next/ に持ちます(ページは Lisp をプロジェクトから読み込み、elisp-studio のプレビューはほかのサイトのものを読み込まないためです)。

mkdir -p vendor/elisp-next
curl -L https://github.com/modeverv/elisp-next/archive/refs/tags/v0.1.2.tar.gz \
  | tar -xz --strip-components=1 -C vendor/elisp-next elisp-next-0.1.2/lisp elisp-next-0.1.2/bin elisp-next-0.1.2/LICENSE

index.html には、elisp-next が書く <script> タグの置き場所を2つ、アプリケーション自身の Lisp の前後に用意します。

<div id="app">Loading Emacs…</div>
<!-- nextel:framework -->
<!-- /nextel:framework -->
<script type="text/emacs-lisp" src="lisp/app-helpers.el"></script>
<!-- nextel:pages -->
<!-- /nextel:pages -->
<script type="module" src="https://modeverv.github.io/elisp-react/js/elisp-react.js"></script>

それからルートを書き出します。Emacs(elisp-studio のものも含む)では次のとおりです。

M-x load-file RET vendor/elisp-next/lisp/nextel-build.el RET   セッションごとに1回
M-x nextel-write-routes     ページを足す・消す・名前を変えたあと
M-x nextel-routes-mode      pages/、api/、shared/ のファイルを保存するたびに

バッチでは vendor/elisp-next/bin/nextel-routes です(--check は CI 用、--watch は別のエディタ用)。routes.el(どのパターンがどのページか。#app にアプリケーションをマウントします)を書き、2つの置き場所を埋めます。ページはディレクトリを一覧できないので、書き出しが必要です。ページのファイルは自分のコンポーネントに名前を付けます。Next.js のファイルが export するのと同じです。

ページ#

;;; pages/channel/[id].el --- /channel/ID
(nextel-page ChannelPage
  :load (lambda (route) (my-load-channel (nextel-param route :id)))
  :head (lambda (route data) (list :title (plist-get data :title) :description (plist-get data :about)))
  :loading (lambda (route) (jsx (p "読み込み中…")))
  :error (lambda (route error retry) (jsx (button (:on-click (lambda (_e) (funcall retry))) "再試行")))
  :render (lambda (self)
            (jsx (h1 (plist-get (nextel-data self) :title)))))

nextel-page は react-define-component(:initial-state、:did-mount などのキーも使えます)に4つのキーを足したものです。

:load (ROUTE)awaitable。つまり、nextel-request が返すような RESOLVE と REJECT の関数です。react-async のタスクは使えません(描画が失敗します。(react-race (list TASK)) で包みます)。答えが来るとページを描き、その値は (nextel-data SELF) です。答えはルートごとに保存され(react-query)、戻るとすぐに表示されます。nextel-stale-ms(60秒)より古ければ、表示したまま裏で読み込み直します。すべて読み込み直すには (nextel-reload) を呼びます。
:loading (ROUTE)、:error (ROUTE ERROR RETRY)待つ間(失敗のあと読み込み直す間も)と、失敗したときに表示するもの。既定は nextel-loading-function、nextel-error-function。
:head (ROUTE DATA)(:title TEXT :description TEXT :meta ((NAME . CONTENT) ...))。文書のタイトルは (funcall nextel-title-function TITLE)。

ページは props として :route(plist (:page :pattern :path :params :query))、:data、そして nextel-page-props-function が全ページに足すものを受け取ります。(nextel-param SELF :id)、(nextel-query SELF "v")、(nextel-data SELF) で読み、(nextel-route) は今表示しているルートです。

;;; pages/_layout.el
(nextel-layout Layout
  :render (lambda (self)
            (jsx (div (header (Link (:href (nextel-href "/")) "ホーム"))
                      (main (react-props self :children))))))
(nextel-href PATTERN PARAMS...)アドレス。(nextel-href "/channel/[id]" :id "UC1") は "#/channel/UC1"、(nextel-href "/watch" :v "x" :t 30) は "#/watch?v=x&t=30"。
(Link (:href HREF ...) CHILD...)リンク。ハッシュ方式ではブラウザが辿る <a>、パス方式では Lisp が辿ります。
(nextel-go PATTERN PARAMS...)、(nextel-navigate HREF [REPLACE])Lisp から移動します。
nextel-navigate-functionsルーターが、パスかクエリの変わったアドレスを描いたあとに呼ぶ ROUTE の関数です。最初のアドレスでも呼びます(先頭へのスクロール、ドロワーを閉じるなど)。:load のあるページでは :loading を描いたときに呼び、データが届いたときには呼びません。
(nextel-reload)、(nextel-refresh)全ページのデータを読み込み直す(データ源が変わったとき)、ページを描き直す(nextel-page-props-function の答えが変わったとき)。
nextel-url-mode、nextel-base-pathhash(既定。#/watch?v=ID。どの静的ホストでも、elisp-studio のプレビューでも動く)または path(nextel-base-path の下の /watch?v=ID。サーバーはどのルートにも index.html を返す必要があります)。

サーバー#

プロジェクトの server.el は次の3行です。

(declare-function nextel-server-load "nextel-server")   ; ないと起動のたびにバイトコンパイラが警告する
(load (expand-file-name "vendor/elisp-next/lisp/nextel-server.el" app-server-project-directory) nil t)
(nextel-server-load)

shared/、api/ の補助ファイル(名前が _ で始まるファイルとディレクトリ)を読み込み、api/ のそれ以外の各ファイルをルートとして読み込みます。各ファイルは、メソッドごとに何をするかを書きます。

;;; api/later.el --- GET と POST /api/later
(nextel-handle "GET"
  :returns '(list-of my-entry)
  :handler (lambda (_request) (app-server-read "later" nil)))

(nextel-handle "POST"
  :accepts 'my-entry
  :returns '(list-of my-entry)
  :handler (lambda (request)
             (app-server-write "later" (cons (plist-get request :body) (app-server-read "later" nil)))))

REQUEST は (:method :path :params :body) です。body はデータで(app-server-data)、評価されることはありません。クエリは (app-server-parameter NAME) で読みます。:accepts に合わない body は、どの項目が違うかを添えて断ります(400、body.id is required)。:returns に合わない答えはサーバーの誤りです(500、ログに出ます)。あとで返す答え(app-server-defer)も同じです。どのファイルのパターンにも合わないパスは 404 です。合えば最も具体的なファイルが答え(api/things/new.el は api/things/[id].el より先)、そのファイルが扱わないメソッドは 405 です。隠しファイル(Emacs のロックファイル .#later.el など)は読み込みません。サーバーはディレクトリを自分で読むので、新しいファイルは次の起動でルートになります。elisp-studio の app-server.el の上で、ネイティブの Emacs(run.sh)でも studio のブラウザのタブでも同じように動きます。

リクエストごとに Emacs を起動する共用ホスト(elisp-studio の CGI、app-server-single-request)では、api/ のすべてではなく、そのリクエストに答えるファイルだけを読み込みます。それ以外では、間違いがすぐ分かるよう、起動時にすべてを読み込みます(nextel-server-lazy で選べます)。ファイルの .elc が新しければそちらを読み込みます。elisp-studio のデプロイは、そこで shared/、api/、elisp-next をコンパイルします。さくらのレンタルサーバ(Emacs 27.2)では、Parens への1リクエストは Emacs の中で 7 ms です。

型#

;;; shared/my-types.el --- ページ(index.html)とサーバーの両方が読み込む
(nextel-defschema my-entry
  "後で見るために保存した動画。"
  (id string :required t)
  (title string)
  (saved number))

これで make-my-entry(検査つき)、my-entry-p、項目の my-entry-id、my-entry-title、my-entry-saved が定義されます。レコードは plist なので、Lisp のデータとして印字し、読み戻せます。型は string、integer、number、boolean、symbol、keyword、any、スキーマの名前、(member VALUE...)、(list-of TYPE)、(vector-of TYPE)、(or TYPE...) です。項目は :required でなければ nil でもかまいません。スキーマにないキーは誤りです。(nextel-check TYPE VALUE) は VALUE を返すか、どこが違うかを添えて nextel-type-error を出します(my-entry.title: expected string, got 42)。型でもスキーマでもない TYPE は、普通の error になります(No type or schema named my-entyr)。

ページは同じ型でサーバーに問い合わせます。

(nextel-request "POST" "/api/later" :body entry :sends 'my-entry :returns '(list-of my-entry))

これは awaitable で、失敗は (:status N :message TEXT) です。答えが :returns に合わなければ :status は nil です(POST /api/later[0].id: expected string, got 42)。項目のアクセサはアプリケーションと同じ名前空間にあるので、スキーマ-項目 が自分の関数とぶつからないようにスキーマの名前を付けます。

制限#

テスト#

test/run-ert.sh    # react.el は ../elisp-react か $ELISP_REACT、app-server.el は ../elisp-studio か $ELISP_STUDIO

lisp/ を警告をエラーとしてコンパイルし、test/nextel-test.el を実行します。型、パターン、ルーター(ページ、:load、:loading、:error と再試行、head、404、フック、パス方式とそのリンク)、nextel-request、ルートの書き出し、サーバー側(ファイルからのルート、:accepts、すぐの答えとあとの答えの :returns、404、405)です。

ライセンス#

MIT(LICENSE)。Emacs の中で動くアプリケーションを公開するときは、GPL と両立するライセンスにする必要があります。MIT はその1つです。