DEV Community: Takashi Masuda

Migrating from asdf and direnv to mise

Takashi Masuda — Sun, 29 Mar 2026 09:27:47 +0000

For managing versions of development tools like Ruby and Node.js, I had gone through *env tools like rbenv and nodenv, then switched to asdf in 2019. For environment variable management, I had been using direnv since even earlier—2014.

Recently, a tool called mise has been gaining attention. I wasn't particularly having issues, but out of curiosity and the motivation to reduce the number of tools—since I heard mise also has direnv-like functionality—I decided to make the switch. My environment is macOS.

jdx / mise

dev tools, env vars, task runner

What is mise?

mise (pronounced "meez") is a tool that handles both development tool version management and environment variable management in one place. It provides asdf-compatible runtime management along with direnv-equivalent environment variable management.

Here are the notable features I found after using it:

Can read .tool-versions (.ruby-version etc. requires configuration, described later)
Can define environment variables and task runners in mise.toml
- The official mise.toml may be a good reference
Supports mise.local.toml for local settings meant to be gitignored. This allows individual adoption even before a team officially adopts mise
Well-organized tool management experience
- mise install installs all tools from .tool-versions in one command
- mise list shows all tool versions and their source files at a glance

What I Did for the Migration

The official documentation has a migration guide from asdf, so start there. Below are the specific steps for my environment.

1. Homebrew Package Changes

I uninstalled asdf and direnv, and installed mise.

$ brew uninstall --force asdf
$ brew uninstall --force direnv
$ brew install mise

2. zsh Configuration Changes

I removed all asdf settings from ~/.zshenv.

-MY_ASDF_CONFIG_HOME="${XDG_CONFIG_HOME}/asdf"
-export ASDF_CONFIG_FILE="${MY_ASDF_CONFIG_HOME}/asdfrc"
-export ASDF_DATA_DIR="${XDG_DATA_HOME}/asdf"
-export ASDF_GEM_DEFAULT_PACKAGES_FILE="${MY_ASDF_CONFIG_HOME}/default-gems"
-export ASDF_NPM_DEFAULT_PACKAGES_FILE="${MY_ASDF_CONFIG_HOME}/default-npm-packages"
-export ASDF_PERL_DEFAULT_PACKAGES_FILE="${MY_ASDF_CONFIG_HOME}/default-perl-modules"
-export ASDF_PYTHON_DEFAULT_PACKAGES_FILE="${MY_ASDF_CONFIG_HOME}/default-python-packages"
-export ASDF_RUBY_BUILD_VERSION=master
-PATH=$ASDF_DATA_DIR/shims:$PATH

I also removed the direnv settings from ~/.zshrc.

-eval "$(direnv hook zsh)"

Instead, I added the mise configuration to ~/.zshrc. Since the activation mechanism enabled by this setting handles PATH management, no configuration in ~/.zshenv is needed.

eval "$(mise activate zsh)"

Here are the actual files:

~/.zshenv (no mise settings)
~/.zshrc

With the asdf-era environment variables gone, my zsh configuration became cleaner.

3. Installing Tools

I reinstalled the tools that asdf had been managing using mise install.

$ cat ~/.tool-versions
nodejs 24.14.0
ruby 4.0.2

$ mise install

$ mise list
Tool       Version   Source            Requested
node       24.14.0   ~/.tool-versions  24.14.0
ruby       4.0.2     ~/.tool-versions  4.0.2

4. Migrating default_packages_file

With asdf, I managed default_packages_file via environment variables in ~/.zshenv. With mise, I consolidated them in ~/.config/mise/config.toml.

[settings.node]
default_packages_file = "~/.config/mise/default-npm-packages"

[settings.ruby]
default_packages_file = "~/.config/mise/default-gems"

During the migration, I discovered a bug where ~ in Node.js's default_packages_file wasn't being expanded, causing default packages not to be installed. I reported it in Discussion#8606, and it was fixed in PR #8709 🙏 This is resolved in v2026.3.11 and later.

5. Configuring .ruby-version and .node-version Support

Neither asdf nor mise reads .ruby-version or .node-version by default. With asdf, you set legacy_version_file = yes in asdfrc, but with mise, the following configuration is needed. I added it to the repository's mise.toml or mise.local.toml.

[settings]
idiomatic_version_file_enable_tools = ["node", "ruby"]

What I Didn't Migrate

Some settings were either unnecessary to migrate or I chose not to migrate.

Ruby pre-install hook
- With asdf, I set RUBY_CONFIGURE_OPTS via pre_asdf_install_ruby, but this turned out to be unnecessary with mise
ASDF_RUBY_BUILD_VERSION=master
- mise automatically fetches the latest version of ruby-build when installing Ruby, so this setting is unnecessary
Perl default-perl-modules
- mise doesn't support default_packages_file for Perl (see the appendix below for a workaround)
direnvrc PATH_add
- I had a configuration to automatically add ./bin to PATH for Ruby projects with a Gemfile.lock
- mise doesn't have an equivalent global feature, but I decided to configure it per-project in mise.toml when needed
```
[env]
_.path = "./bin"
```

Conclusion

I replaced two tools—asdf + direnv—with just mise. The zsh configuration became cleaner, and being able to consolidate tool versions and environment variables in mise.toml is a nice benefit.

There were some gotchas like the Emacs compatibility issue described in the appendix below, but overall I'm happy with the migration.

Also, with direnv no longer needed, I was able to migrate from .envrc to .env, which later enabled me to set up .env mounting with 1Password Environments.

References

Appendix

Fixing ruby-lsp Not Working in Emacs

I encountered an issue where ruby-lsp wouldn't work in Emacs for repositories using a Ruby version different from the global one.

mise activate zsh takes a hook-based approach, using zsh's chpwd hook to switch tool versions when changing directories. However, Emacs doesn't execute this hook, so mise's version switching doesn't work.

mise offers an alternative to hook-based activation called shims.

	activate	shims
Best for	Interactive shell	Non-interactive (IDE, Emacs, scripts)
Hooks like `cd`	Triggered	Not triggered
`which` result	Returns the actual tool path	Returns the shim path

Initially, I added eval "$(mise activate zsh --shims)" to ~/.zshrc to enable both, but the mise documentation assumes activate and shims are mutually exclusive.

I ultimately settled on the following setup:

eval "$(mise activate zsh)" in ~/.zshrc (for interactive shell)
Add the shims directory to PATH only when launching Emacs

alias emacs="LC_COLLATE=C PATH='${XDG_DATA_HOME}/mise/shims:$PATH' emacs"

This creates a separation of concerns: regular zsh sessions use hooks only, while Emacs uses shims.

Compared to asdf's simpler shims-only design, this setup might look more complex at first glance. However, I understand this is a tradeoff stemming from mise being a replacement for both asdf and direnv. The real-time reflection of environment variable changes in the interactive shell via mise activate is something shims alone cannot achieve.

Workaround for Perl default-packages

mise's default-packages mechanism is a language-specific feature hardcoded in core plugins (Go, Node.js, Python, Ruby). Perl is not a core plugin—it's installed via the Aqua backend—so it's not covered.

As a workaround, you can run cpanm in mise.toml's [hooks] postinstall¹. This way, mise install alone sets up both Perl and CPAN modules.

[settings]
experimental = true

[hooks]
postinstall = "cpanm CGI HTML::Template"

Note that hooks is an experimental feature, so experimental = true is required. Also, postinstall runs on every tool installation, not just Perl, so this hook will be triggered every time you run mise install.

The Relationship Between mise and aqua

aqua is a tool specialized in version management for CLI tools (terraform, gh, etc.), with robust security through checksum verification. While mise and aqua cover different scopes, mise can use aqua-registry as a backend (via the aqua: prefix), allowing you to install tools managed by aqua through mise.

They're not identical, but for personal dotfiles management, I feel mise alone can sufficiently cover aqua-like use cases. If your team uses aqua or you need checksum verification for supply chain security in CI/CD, there's still value in using aqua separately.

Hooks | mise-en-place ↩

Created a GitHub Actions Reusable Workflows Repository for Personal Use

Takashi Masuda — Mon, 23 Feb 2026 10:00:48 +0000

I created a GitHub Actions Reusable Workflows repository for my personal use.

masutaka / actions

GitHub Actions reusable workflows

What Are GitHub Actions Reusable Workflows?

GitHub Actions' reusable workflows is a mechanism that allows workflow files to be called from other repositories.

For example, you can call a workflow from another repository like this:

jobs:
  example:
    uses: masutaka/actions/.github/workflows/some-workflow.yml@main

Since you can consolidate common processes in one place, it saves you the trouble of managing the same workflow across multiple repositories.

There are some limitations and caveats to be aware of:

Reusable workflows in private repositories cannot be called from public repositories
Reusable workflows in private repositories can only be called from other repositories within the same org/user (different orgs are not allowed, and the Access policy setting of the called repository must be configured)
The env context at the calling workflow level is not propagated to the called workflow
Environment secrets cannot be passed (only regular secrets can be passed via secrets: inherit)
Reusable workflows always run at the job level (they cannot be used as steps). This means a separate runner starts each time they are called, and the filesystem cannot be shared between jobs. For private repositories, this also increases Actions minutes consumption. If you want to reuse at the step level, you need to use a composite action

Since masutaka/actions is a public repository, limitations 1 and 2 do not apply.

Included Workflows

Currently, I have included the following reusable workflows:

add_assignee_to_pr.yml (docs) - Sets the PR creator as the assignee when a PR is created
codeql.yml (docs) - Detects languages from changed files and runs CodeQL analysis
codeql_core.yml (docs) - Runs CodeQL analysis for specified languages
create_gh_issue.yml (docs) - Creates a GitHub Issue from a template
dependency_review.yml (docs) - Reviews PR dependencies
pushover.yml (docs) - Sends Pushover¹ notifications for workflow failures

I referenced mdn/workflows for the documentation structure, documenting each workflow's usage in Markdown files under docs/ and linking to them from README.md.

Why I Created This

I had been using route06/actions, a repository where I had been a maintainer at my previous job, even after leaving the company.

However, there were a few things I wanted to customize for personal use, and creating a new pushover.yml workflow prompted me to copy the necessary workflow files and create my own repository.

Up until then, the same pushover.yml file was duplicated across my personal repositories, but I took this opportunity to consolidate everything into masutaka/actions.

Handling Licenses

Both repositories are under the MIT License. For workflow files copied over, I added attribution to the original repository at the top of each file like this:

Example: codeql.yml:

# Derived from https://github.com/route06/actions/blob/main/.github/workflows/codeql.yml
# Copyright (c) 2024 ROUTE06, Inc.
# Licensed under the MIT License.

I also included both copyrights in the LICENSE file. I believe this satisfies the requirements of the MIT License.

Copyright (c) Takashi Masuda
Copyright (c) 2024 ROUTE06, Inc.

Conclusion

Until now, similar workflow files were scattered across my personal repositories, and I had to update multiple repositories every time a change was needed. By consolidating them into masutaka/actions, changes can now be made in one place.

As my personal repositories continue to grow, I plan to keep consolidating shareable workflows here going forward.

References

A push notification service for iOS/Android ↩

Created a Rails 8 Learning Repository and Started Recovering from a 6-Year Blank with Rails Guides and Claude Code

Takashi Masuda — Tue, 30 Dec 2025 05:17:38 +0000

Last month I changed jobs and returned to Rails development after a long time.

With a 6-year gap and only one month available for learning, I needed to efficiently grasp Rails 8's new features and refresh my memory of existing ones.

So I decided to learn by building a working app together with Claude Code while referencing the Rails Guides. I temporarily subscribed to Claude Code's Max plan at USD 100/mo.

Here's the repository I created:

masutaka / trial-rails8

Rails ガイドを元にした素振り

Learning Process

I used the Rails Guides as my main reference material.

1. Reviewing the Basics with Rails Guides

Following Getting Started with Rails, I created /products. I mainly learned about Active Storage (image uploads) and Action Text (rich text).

2. Learning Hotwire and Solid Trifecta

To learn Hotwire and Solid Trifecta, I created /chat and /posts.

/chat: Learned Action Cable, Solid Cable, and Stimulus
/posts: Learned Turbo Streams/Frames, Active Job, and Solid Queue. Added comment, follow, and notification features to a typical blog functionality

I learned through AI pair programming with Claude Code. The specific workflow was as follows:

Create a GitHub Issue (e.g., #14 Follow Feature)
Have Claude Code create a plan document (e.g., docs/plan-for-issue-14.md)
Have it create a PR based on the plan while understanding the implementation (e.g., #38)

I also utilized AI reviews from CodeRabbit. It pointed out N+1 queries and suggested adding tests, allowing me to maintain quality even in solo development. It's great that it's free for OSS.

Rails Features I Learned

Hotwire

Hotwire is a framework introduced in Rails 7 for achieving SPA-like UX. Hotwire consists of Turbo and Stimulus.

Turbo is further composed of three parts:

Turbo Drive: Speeds up page transitions (fetches and replaces HTML on link clicks)
Turbo Frames: Updates parts of a page (inline editing of comments, etc.)
Turbo Streams: Updates multiple locations simultaneously (updates list and count when adding comments)

Stimulus is a JavaScript framework, but it's a very thin layer for adding minimal JS with HTML as the starting point. I used it for UI control in the chat feature.

I utilized Turbo Streams in the comment feature. When a comment is posted, model callbacks broadcast it to other users' browsers in real-time.

# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :post, counter_cache: true
  belongs_to :user

  after_create_commit do
    # Append to comment list
    broadcast_append_to post,
                        target: "comments",
                        partial: "comments/comment",
                        locals: { comment: self, allow_actions: false }
    # Update comment count
    broadcast_replace_to post,
                         target: "comment_count_#{post.id}",
                         partial: "posts/comment_count",
                         locals: { post: post }
  end
end

Solid Trifecta

"Solid Trifecta" introduced in Rails 8 eliminates the need for external middleware like Redis or Memcached.

Solid Queue: Database-based Active Job backend
Solid Cable: Database-based Action Cable adapter
Solid Cache: Database-based cache store (not used this time)

I used Active Job + Solid Queue for the scheduled post feature. When you set a future datetime for published_at, a job executes at that time to publish the article.

# app/jobs/publish_post_job.rb
class PublishPostJob < ApplicationJob
  queue_as :default

  def perform(post_id, scheduled_at)
    post = Post.find_by(id: post_id)
    return unless post

    # Idempotency: Skip if already published
    return if post.published

    # Skip if publish datetime was changed
    return if post.published_at.blank? || post.published_at.to_i != scheduled_at

    post.update!(published: true)
  end
end

You can check job execution status with Mission Control Jobs. Access http://localhost:3000/jobs in development to view job history and queue status in a Web UI.

Other Features

Eager Loading: includes/preload/eager_load to prevent N+1 queries
has_secure_password + rate_limit: User authentication and rate limiting
Counter Cache: Efficient retrieval of comment counts (belongs_to :post, counter_cache: true)
Foreign key constraint on_delete: :cascade: Automatically deletes child records when parent is deleted. Used alongside Rails' dependent: :destroy to maintain DB-level integrity
Shallow Routing: Specifying shallow: true for nested resources shortens URLs for member actions (show/edit/update/destroy)
Polymorphic Association: Used for notification feature. Manages follow and comment notifications uniformly
Self-Referential Association: Used for follow feature. Expresses many-to-many relationships with a single follows table

Conclusion

Despite a 6-year gap, I was able to learn efficiently with Rails Guides and Claude Code.

Note that I didn't write many tests this time. The goal was to learn Rails features, so I'll save test learning for another time.

My mental model was stuck around the time of "temporarily disabling Turbolinks...", so I was quite impressed by Hotwire's ability to achieve SPA-like UX with almost no JavaScript. My memory of Rails was that it often served as an API server or adopted React for the frontend, but I now think Hotwire should be considered first.

Solid Queue and Solid Cable are also nice because you can start with just RDS, reducing the number of components.

I'll continue working through the open Issues while continuing to learn.

References

Finally Modernized My Emacs Setup with LSP + Tree-sitter

Takashi Masuda — Mon, 24 Nov 2025 10:13:19 +0000

In recent years, I've been mainly writing LookML, SQL, HCL, and other languages, with fewer opportunities to write programming languages like Ruby. However, I've recently returned to Rails development this month.

So, I finally got around to setting up LSP (Language Server Protocol) in Emacs.

During this process, I also learned about Tree-sitter and configured it as well.

※ LSP is an advanced code assistance mechanism provided by Language Servers, while Tree-sitter is a parsing engine that quickly generates AST from code to enable highlighting and structural editing.

Emacs Version I'm Using

I'm using Emacs 29.1 instead of the latest 30.2 for the following reasons:

I use railwaycat/homebrew-emacsmacport with Mac port patch
- I rely on some useful features provided by the Mac port patch
The latest Mac port patch is emacs-29.4-mac-10.1 and hasn't caught up to version 30
railwaycat/homebrew-emacsmacport@emacs-29.4-mac-10.1 with the patch has issue #389 on my environment
Therefore, I'm using railwaycat/homebrew-emacsmacport@emacs-29.1-mac-10.0

Introducing LSP

Adopted lsp-mode

I compared eglot, which is standard in Emacs 29, with the third-party lsp-mode.

I would have preferred to use the standard eglot, but I decided to adopt lsp-mode because there's information suggesting that Solargraph, which eglot requires as the Ruby Language Server, doesn't have good performance. lsp-mode requires ruby-lsp as the Language Server.

I haven't actually verified whether Solargraph really has poor performance 😅

lsp-mode Configuration Example

First, install the Language Server for each language in a PATH that Emacs recognizes (exec-path).

The correspondence between each language and Language Server is documented in Languages in the lsp-mode documentation.

Here are the Language Servers I installed this time:

Lang	Language Server
Dockerfile	dockerfile-language-server-nodejs
Go	gopls
JSON	vscode-json-languageserver
Ruby	ruby-lsp, ruby-lsp-rails
TypeScript	typescript-language-server

Next, install lsp-mode from Melpa.

Finally, just add the lsp-deferred function to the hook of the major-mode you want to enable.

Here's a configuration example for ruby-mode:

(add-hook 'ruby-mode-hook #'lsp-deferred)

With this, you can jump to definitions with M-. and return with M-,, and it also points out indentation issues. For other features, please see the lsp-mode documentation.

I also configured the following:

(setq lsp-keymap-prefix "C-c C-l")

;; Disable rubocop-ls so that ruby-lsp is prioritized even when rubocop is installed.
(setq lsp-disabled-clients '(rubocop-ls))

;; Format files on save for all buffers where lsp-mode is active.
(setq-default lsp-format-buffer-on-save t)

Discovered xxx-ts-mode Has Been Added to Emacs

When trying to configure lsp-mode for TypeScript, I noticed that xxx-ts-mode exists, which wasn't in previous versions of Emacs.

$ find /Applications/Emacs.app -type f -name '*-ts-mode.elc' | sort
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/c-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/cmake-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/dockerfile-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/go-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/java-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/json-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/ruby-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/rust-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/typescript-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/textmodes/toml-ts-mode.elc
/Applications/Emacs.app/Contents/Resources/lisp/textmodes/yaml-ts-mode.elc

Unlike traditional xxx-mode which parses syntax using regular expressions, xxx-ts-mode parses syntax at the AST level using Tree-sitter. Therefore, syntax highlighting is more accurate, and indentation and structural editing are more stable.

I was about to skip it, but when I looked at typescript-mode's README.md, I learned that development has stopped:

Essentially all major development of typescript-mode has come to a halt.

So I decided to introduce xxx-ts-mode, starting with typescript-ts-mode. I also felt the benefit of being able to drop third-party xxx-mode packages.

Introducing typescript-ts-mode

You can install the Tree-sitter for TypeScript by adding the following to init.el:

(setq treesit-language-source-alist
      '((tsx "https://github.com/tree-sitter/tree-sitter-typescript" "v0.23.2" "tsx/src")
        (typescript "https://github.com/tree-sitter/tree-sitter-typescript" "v0.23.2" "typescript/src")))

(dolist (element treesit-language-source-alist)
  (let ((lang (car element)))
    (unless (treesit-language-available-p lang)
      (treesit-install-language-grammar lang))))

When this is evaluated, the *.dylib files built from source code fetched from GitHub will be installed directly under ~/.emacs.d/tree-sitter/.

libtree-sitter-tsx.dylib
libtree-sitter-typescript.dylib

💡 If you don't specify a tag, the default branch will be referenced. Since commit hash couldn't be specified, I specified tags from the perspective of security and version pinning.

Then, simply associate *.ts and *.tsx with typescript-ts-mode and tsx-ts-mode respectively. Also enable lsp-mode.

※ tsx-ts-mode is also defined in typescript-ts-mode.el.

;; TypeScript

(add-to-list 'auto-mode-alist '("\\.ts\\'" . typescript-ts-mode))

(defun typescript-ts-mode-hook-func ()
  (lsp-deferred))
(add-hook 'typescript-ts-mode-hook #'typescript-ts-mode-hook-func)

;; TSX

(add-to-list 'auto-mode-alist '("\\.tsx\\'" . tsx-ts-mode))

(defun tsx-ts-mode-hook-func ()
  (lsp-deferred))
(add-hook 'tsx-ts-mode-hook #'tsx-ts-mode-hook-func)

Supplement: Why I Didn't Adopt the tree-sitter-langs Package

The tree-sitter-langs package can also install *.dylib, but I decided not to adopt it for the following reasons:

It installs under ~/.emacs.d/elpa/tree-sitter-langs-20251019.1145/bin/ instead of ~/.emacs.d/tree-sitter/
- This directory name will change with version updates of the tree-sitter-langs package
The library names are like typescript.dylib instead of libtree-sitter-typescript.dylib

It's good for checking the location of Tree-sitter parsers for each language:

https://github.com/emacs-tree-sitter/tree-sitter-langs/tree/master/repos

Introducing Other xxx-ts-modes

Among the Emacs built-in xxx-ts-modes mentioned earlier, I introduced those with high usage frequency:

dockerfile-ts-mode
go-ts-mode
json-ts-mode
ruby-ts-mode

As an exception, I didn't introduce yaml-ts-mode. When saving, it formats with indent 4, and I couldn't figure out how to change it to 2.

Final Configuration for LSP mode, Tree-sitter, and xxx-ts-mode

LSP mode: init.el#L1044-L1063
Tree-sitter: init.el#L1431-L1450
dockerfile-ts-mode: init.el#L801-L810
go-ts-mode: init.el#L905-L917
json-ts-mode: init.el#L980-L989
ruby-ts-mode: init.el#L1121-L1132
typescript-ts-mode: init.el#L1014-L1028

Bonus: Migration from auto-complete to company-mode

There were usage points for company-mode in the lsp-mode code.

I had only heard the name company-mode, but apparently it's a completion framework that assists code input.

I migrated from auto-complete, which I've been using for years, to company-mode.

I saw some information suggesting that corfu, which is lighter than company-mode, might be better now, but I decided to go with company-mode this time as it seemed easier.

(setq company-minimum-prefix-length 2)
(setq company-show-quick-access t)

(add-hook 'after-init-hook #'global-company-mode)

Issues

When lsp-format-buffer-on-save is enabled for all buffers where lsp-mode is active, code written by others gets heavily reformatted, which might be awkward. Especially YAML files
global-company-mode is a bit noisy, so it might be better to configure it for individual major-modes. I might change this later

Conclusion

Finally, I brought my Emacs setup closer to a modern configuration with LSP + Tree-sitter. However, since there are almost no Emacs users around me, I'm not entirely sure how close I got.

I was also able to reduce some third-party packages. I want to minimize dependencies as much as possible, so that's good.

Added:
- company
- lsp-mode
Removed:
- auto-complete
- dockerfile-mode
- go-autocomplete
- go-eldoc
- go-mode

References

Making this Hugo-built blog multilingual

Takashi Masuda — Tue, 23 Sep 2025 12:17:05 +0000

I've made this blog built with Hugo multilingual. For now, it's only available in English.

Why I implemented multilingual support

As part of my OSS activities at work, I often cross-post translated articles to platforms like dev.to and Medium. Recently, I've been casually translating and cross-posting articles on my own as well.

For example, the English translation of 2025-08-15-1 was cross-posted to these three sites:

dev.to - This served as the original English version
Hashnode - Set dev.to's article as the canonical version
Medium - Set dev.to's article as the canonical version

However, since I'm maintaining this blog masutaka.net, I thought it would be better to store the original English articles here and cross-post them to the above three sites. Setting the canonical URL to my own blog seems like it would also be beneficial for SEO.

Hugo's Multilingual Support

Hugo includes built-in multilingual support with simple configuration. All you need to do is add the following settings in your config.toml file:

defaultContentLanguage = "ja"

[languages.ja]
  weight = 1
  languageName = "日本語"
  title = "マスタカの ChangeLog メモ"

[languages.en]
  weight = 2
  languageName = "English"
  title = "Masutaka's ChangeLog Memo"

Articles with .en.md in their filenames will be the English versions.

Japanese version: content/posts/2025-08-15-1.md
English version: content/posts/2025-08-15-1.en.md

With this configuration, articles can be accessed via the following URLs:

Japanese version: https://masutaka.net/2025-08-15-1/
English version: https://masutaka.net/en/2025-08-15-1/

Multilingual Implementation Strategy

When implementing multilingual support, I followed this approach:

1. Maintain Existing URLs Unchanged

The most important policy was to absolutely preserve all existing URLs. Given that this blog has been operational for over 20 years, any changes to URLs would cause numerous broken links.

Therefore, I kept the Japanese version as is and added an /en/ prefix only for the English version.

/index.html - Almost unchanged, with /en/index.html added
/index.xml - Unchanged, with /en/index.xml added
/sitemap.xml - Changed to reference /ja/sitemap.xml and /en/sitemap.xml
/llms.txt, /llms-full.txt - Unchanged, with /en/llms.txt and /en/llms-full.txt added
- See reference: 2025-05-18-1

👉 The behavior described above is achieved through the configuration settings for defaultContentLanguage, [languages.ja], and [languages.en].

2. Keep English Menu Options in the Top Right Minimal

The Device, History, and About pages contain content that is primarily Japanese-specific with limited value in translation, so I decided to skip them this time.

Japanese Version: Archive, Tags, Search, Device, History, About
English Version: Only includes Archive, Tags, Search

Implementation Details

Here's an overview of the actual changes.

1. Modifications to config.toml

Added language configuration settings and corresponding menu settings for each language.

👉 The diff and the updated config.toml are attached in the Appendix.

2. Creating English versions of static pages

content/archives.en.md - Archives page
content/search.en.md - Search page
content/privacy.en.md - Privacy Policy

⚠️ Initially, I attempted to handle this by creating symbolic links from *.en.md to *.md, but Hugo did not recognize these links.

3. Modifying custom shortcodes

Updated the custom post shortcode to accept an lang argument.

layouts/shortcodes/post.html:

{{- $id := .Get "id" | default (.Get 0) -}}
{{- $lang := .Get "lang" | default .Page.Lang -}}
{{- $url := relref . (dict "path" $id "lang" $lang) -}}
{{- $title := .Get "title" -}}

<a href="{{ $url }}">{{ with $title }}{{ $title }}{{ else }}[{{ $id }}]{{ end }}</a>

Example usage:

<!-- If you specify an article ID as an argument, it generates a link in the current language -->
{{< post "2025-09-23-1" >}}
<!-- -> If the current language is English, this will generate a link to /en/2025-09-23-1/ -->

<!-- Adding the 'lang' argument creates an explicit link to another language -->
{{< post id="2025-09-23-1" lang="ja" >}}
<!-- -> If the current language is English, this will generate a link to /2025-09-23-1/ -->

4. Translation Support for Custom Partials

Since some translations were needed in layouts/partials/*.html, I created i18n/ja.toml and i18n/en.toml files.

Usage example:

<a href="https://example.com/" target="_blank" rel="noopener">{{ i18n "sendMessage" }}</a>

i18n/ja.toml:

sendMessage = "メッセージ送信"

i18n/en.toml:

sendMessage = "Send Message"

Conclusion

I successfully added multilingual support to this Hugo-built blog. The implementation was cleaner than I expected 👍

All existing URLs remained unchanged, limiting the impact to the /en/ directory
Achieved using only Hugo's standard features with minimal customization
Reduced maintenance costs by keeping the English menu minimal
sitemap.xml and llms.txt were automatically multilingualized

Moving forward, I'll translate new articles as needed and use https://masutaka.net/en/ as the original source while cross-posting to dev.to, Hashnode, and Medium.

While I'm not sure if there's actually an English-speaking audience, I'm satisfied with the result. With recent AI translation being fairly accurate, it's not that difficult anyway 😎

References

Multilingual mode - Hugo

Appendix

Changes to config.toml

diff --git a/config.toml b/config.toml
index 0830be8b..a6bae12c 100644
--- a/config.toml
+++ b/config.toml
@@ -7,7 +7,6 @@ googleAnalytics = "G-K28CQCC064"
 hasCJKLanguage = true
 languageCode = "ja"
 theme = "papermod"
-title = "マスタカの ChangeLog メモ"

 [permalinks]
   posts = "/:filename"
@@ -27,14 +26,12 @@ title = "マスタカの ChangeLog メモ"
   isPlainText = true
   mediaType = "text/plain"
   rel = "alternate"
-  root = true

 [outputFormats.llmsfull]
   baseName = "llms-full"
   isPlainText = true
   mediaType = "text/plain"
   rel = "alternate"
-  root = true

 #
 # papermod configuration
@@ -51,14 +48,9 @@ title = "マスタカの ChangeLog メモ"
   author = "masutaka"
   comments = true
   defaultTheme = "auto"
-  description = "マスタカの変更履歴が記録されていくブログです。"
   showtoc = true
   tocopen = true

-[params.homeInfoParams]
-  Title = "マスタカネット"
-  Content = "マスタカの変更履歴が記録されていくブログです。"
-
 [params.assets]
   theme_color = "#ffffff"
   msapplication_TileColor = "#da532c"
@@ -79,46 +71,81 @@ title = "マスタカの ChangeLog メモ"
 [[params.socialIcons]]
   name =  "GitHub"
   url = "https://github.com/masutaka"
-[[params.socialIcons]]
-  name =  "Dev"
-  url = "https://dev.to/masutaka"
-[[params.socialIcons]]
-  name =  "Hashnode"
-  url = "https://masutaka.hashnode.dev/"
-[[params.socialIcons]]
-  name =  "Medium"
-  url = "https://medium.com/@masutaka"
 [[params.socialIcons]]
   name =  "RSS"
   url = "/index.xml"

-[[menu.main]]
+#
+# Multilingual
+#
+
+[languages.ja]
+  weight = 1
+  languageName = "日本語"
+  title = "マスタカの ChangeLog メモ"
+
+[languages.ja.params]
+  description = "マスタカの変更履歴が記録されていくブログです。"
+
+[languages.ja.params.homeInfoParams]
+  Title = "マスタカネット"
+  Content = "マスタカの変更履歴が記録されていくブログです。"
+
+[[languages.ja.menu.main]]
   identifier = "archives"
   name = "Archive"
   url = "/archives/"
   weight = 1
-[[menu.main]]
+[[languages.ja.menu.main]]
   identifier = "tags"
   name = "Tags"
   url = "/tags/"
   weight = 2
-[[menu.main]]
+[[languages.ja.menu.main]]
   identifier = "search"
   name = "Search"
   url = "/search/"
   weight = 3
-[[menu.main]]
+[[languages.ja.menu.main]]
   identifier = "device"
   name = "Device"
   url = "/device/"
   weight = 4
-[[menu.main]]
+[[languages.ja.menu.main]]
   identifier = "history"
   name = "History"
   url = "/history/"
   weight = 5
-[[menu.main]]
+[[languages.ja.menu.main]]
   identifier = "about"
   name = "About"
   url = "/about/"
   weight = 6
+
+[languages.en]
+  weight = 2
+  languageName = "English"
+  title = "Masutaka's ChangeLog Memo"
+
+[languages.en.params]
+  description = "This is a blog that records Masutaka's change history."
+
+[languages.en.params.homeInfoParams]
+  Title = "Masutaka Net"
+  Content = "This is a blog that records Masutaka's change history."
+
+[[languages.en.menu.main]]
+  identifier = "archives"
+  name = "Archive"
+  url = "/en/archives/"
+  weight = 1
+[[languages.en.menu.main]]
+  identifier = "tags"
+  name = "Tags"
+  url = "/en/tags/"
+  weight = 2
+[[languages.en.menu.main]]
+  identifier = "search"
+  name = "Search"
+  url = "/en/search/"
+  weight = 3

config.toml after multilingualization

baseURL = "https://masutaka.net/"
defaultContentLanguage = "ja"
disablePathToLower = true
enableEmoji = true
enableRobotsTXT = true
googleAnalytics = "G-K28CQCC064"
hasCJKLanguage = true
languageCode = "ja"
theme = "papermod"

[permalinks]
  posts = "/:filename"

[taxonomies]
  tag = "tags"

[markup.goldmark.renderer]
  hardWraps = true
  unsafe = true

[outputs]
  home = ["html", "rss", "llms", "llmsfull"]

[outputFormats.llms]
  baseName = "llms"
  isPlainText = true
  mediaType = "text/plain"
  rel = "alternate"

[outputFormats.llmsfull]
  baseName = "llms-full"
  isPlainText = true
  mediaType = "text/plain"
  rel = "alternate"

#
# papermod configuration
#

[params]
  AmazonJpAffiliateID = "masutaka04-22"
  DateFormat = "2006-01-02 (Mon)"
  ShowAllPagesInArchive = true
  ShowCodeCopyButtons = true
  ShowFullTextinRSS = true
  ShowPageNums = true
  ShowPostNavLinks = true
  author = "masutaka"
  comments = true
  defaultTheme = "auto"
  showtoc = true
  tocopen = true

[params.assets]
  theme_color = "#ffffff"
  msapplication_TileColor = "#da532c"

[params.social]
  fediverse_creator = "@masutaka@mstdn.love"
  twitter = "@masutaka"

[[params.socialIcons]]
  name =  "Mastodon"
  url = "https://mstdn.love/@masutaka"
[[params.socialIcons]]
  name =  "Bluesky"
  url = "https://bsky.app/profile/masutaka.net"
[[params.socialIcons]]
  name =  "Twitter"
  url = "https://twitter.com/masutaka"
[[params.socialIcons]]
  name =  "GitHub"
  url = "https://github.com/masutaka"
[[params.socialIcons]]
  name =  "RSS"
  url = "/index.xml"

#
# Multilingual
#

[languages.ja]
  weight = 1
  languageName = "日本語"
  title = "マスタカの ChangeLog メモ"

[languages.ja.params]
  description = "マスタカの変更履歴が記録されていくブログです。"

[languages.ja.params.homeInfoParams]
  Title = "マスタカネット"
  Content = "マスタカの変更履歴が記録されていくブログです。"

[[languages.ja.menu.main]]
  identifier = "archives"
  name = "Archive"
  url = "/archives/"
  weight = 1
[[languages.ja.menu.main]]
  identifier = "tags"
  name = "Tags"
  url = "/tags/"
  weight = 2
[[languages.ja.menu.main]]
  identifier = "search"
  name = "Search"
  url = "/search/"
  weight = 3
[[languages.ja.menu.main]]
  identifier = "device"
  name = "Device"
  url = "/device/"
  weight = 4
[[languages.ja.menu.main]]
  identifier = "history"
  name = "History"
  url = "/history/"
  weight = 5
[[languages.ja.menu.main]]
  identifier = "about"
  name = "About"
  url = "/about/"
  weight = 6

[languages.en]
  weight = 2
  languageName = "English"
  title = "Masutaka's ChangeLog Memo"

[languages.en.params]
  description = "This is a blog that records Masutaka's change history."

[languages.en.params.homeInfoParams]
  Title = "Masutaka Net"
  Content = "This is a blog that records Masutaka's change history."

[[languages.en.menu.main]]
  identifier = "archives"
  name = "Archive"
  url = "/en/archives/"
  weight = 1
[[languages.en.menu.main]]
  identifier = "tags"
  name = "Tags"
  url = "/en/tags/"
  weight = 2
[[languages.en.menu.main]]
  identifier = "search"
  name = "Search"
  url = "/en/search/"
  weight = 3

Migration from Pocket and Hatena Bookmark to Raindrop.io (and Creating helm-raindrop.el)

Takashi Masuda — Fri, 15 Aug 2025 10:39:11 +0000

I've migrated from Pocket and Hatena Bookmark (Hatebu), services I had been using for over a decade, to a new bookmarking service: Raindrop.io. I've also created helm-raindrop.el so I can comfortably search from Emacs as before.

What is Raindrop.io?

🔗 https://raindrop.io/

Raindrop.io is a bookmarking service with a modern design and rich features.

Organize bookmarks with collections
Tagging and smart filters
Full-text search (premium plan only)
Browser extensions, mobile apps
Integrations with external services like IFTTT and Zapier
REST API for developers

The backend is proprietary, but everything else is open-source (OSS) and maintained by a single person, Rustem Mussabekov, who lives in Kazakhstan.

raindropio / app

Source code of web app and browser extensions

raindropio / mobile

Official Raindrop.io mobile app for Android

raindropio / desktop

Official Raindrop.io Desktop App

Migration Pocket and Hatebu to Raindrop.io

On July 8, 2025, Pocket was discontinued. I had used it as a "read-it-later" service for many years, so I had to find an alternative.

I had also been using Hatebu for a full 16 years since 2009, but since I've been distancing myself from social media in recent years, I decided to switch to a unified service.

Here's why I chose Raindrop.io:

The free plan is more than enough (unlimited bookmarks)
I can use it as a "read-it-later" service, just like Pocket
I can also use it as a persistent bookmarking service, like Hatebu
The API is public, making it easy to create my own tools
It has a data export feature, so there's less worry about vendor lock-in

The good things about Raindrop.io

After using it, I found several convenient features.

The free plan is practical

URLs can be edited - You can correct the URL later even if it changes
Collections feature - You can organize bookmarks like folders and set them to be public or private individually
Nested collections - You can set up a hierarchical structure
Highlighting feature - You can mark important parts of an article
Mobile app - In addition to the web version, browser extensions, and desktop version, there are also apps for iOS and Android

The paid plan's automated web archiving is convenient

🔗 https://help.raindrop.io/premium-features

AI-powered suggestions - It suggests appropriate collections and tags when saving and suggests merging or renaming similar tags
Full-text search - It performs a full-text search on the content of saved articles
Automated web archiving feature - It permanently saves content even if the site disappears
Reminder feature - It notifies you of a specific bookmark via the app or email at a specified time
Annotation feature - You can add notes to highlights
Detection of duplicate and broken links - Makes maintenance easier (?)
Automated backup - You can manage versions by linking with Google Drive
Extended upload limit - You can upload up to 10GB of images, videos, and PDFs per month

I tried the paid plan and found the automated web archiving to be very convenient.

I can't help but fix broken links when I find them. I know some might argue that if you can't find them, you don't have to maintain them...

While fixing them, I realized that many of my past bookmarks were inaccessible. With Raindrop.io's automated web archiving, a new reason is added to "read-it-later" or "bookmark": "it'll be readable forever."

The current paid plan is $33.04 per year (tax included), which is about $3.54 per month (tax included), so it's not a bad price.

The bad things about Raindrop.io

It's not a perfect service, so there are a few points that are difficult to use.

The app icon is plain - It's difficult to spot in my smartphone's share menu, and I often have to search for it
The saving process is a bit sluggish - It feels like it takes an extra 1-2 seconds to save a bookmark compared to Pocket
No archiving feature - If you're looking for a 'mark as read' feature like Pocket's, you'll need to create a dedicated collection and manually move bookmarks to it (which requires two taps)

However, even with these points, it's still a good and very usable service.

I created helm-raindrop.el

For this migration, I created helm-raindrop.el, which allows you to search and browse Raindrop.io bookmarks from Emacs.

masutaka / emacs-helm-raindrop

Helm interface for Raindrop.io

I'm not following what's next after Helm, but since the main function of helm-raindrop.el is to create a cache file ~/.emacs.d/helm-raindrop with the REST API, I don't think it will be difficult to migrate later.

Actually, I had a similar tool for Hatebu, and its extreme convenience was one of the reasons I was hesitant to migrate.

masutaka / emacs-helm-hatena-bookmark

Helm interface for Hatena::Bookmark

Being able to search bookmarks quickly from Emacs is quite comfortable. For example, if I think, "where was that article?", I just press ⌘-b and enter a search word. That's what my init.el does.

I'm not sure if it's a good or bad thing that I can continue to search for bookmarks from Emacs, but for now, I've managed to maintain the status quo.

Conclusion

Following the discontinuation of Pocket, I migrated to Raindrop.io, including Hatebu, which I had used for a full 16 years. At first, it was a reluctant migration, but after using it, I found it to be a surprisingly good service.

The free plan is practical, and the paid plan is also reasonably priced at $33.04 per year (tax included)
The API is public, making it easy to integrate with self-made tools
It has modern features like AI and automated web archiving

I also created helm-raindrop.el, so I've been able to maintain the ability to search from Emacs.

I recommend it to anyone looking for a bookmarking service. The free plan is very usable, and migrating from Pocket or Hatebu is easy, so it's a good idea to give it a try.

I'll continue to use it and will write another article if I discover anything new.

Self-implemented IFTTT Pro's RSS feed notification feature with AWS serverless architecture

Takashi Masuda — Sun, 20 Jul 2025 09:49:18 +0000

For casual information gathering, I've been running a serverless application called masutaka-feed since 2020.

masutaka / masutaka-feed

Notify my feeds of github and hatebu to mastodon and pushover

Post GitHub private feeds¹ to Mastodon
- Star and follow notifications are also sent to Pushover
Post Hatena Bookmark favorites feeds² to Mastodon

These are pieces of information that aren't worth subscribing to seriously with a feed reader, but I want to keep them in my field of view.

※ Mastodon posts are made to the private account @masutakafeed@mstdn.love

Previous Architecture Diagram
Current Architecture Diagram
Current Architecture
- Periodic execution with EventBridge Scheduler
- Lambda function responsibility separation
- Duplicate prevention with DynamoDB
- Configuration management with SAM continues
After the migration
Implemented with Claude Code
Conclusion

Previous Architecture Diagram

Previously, I used IFTTT's RSS Feed Integration to detect new items and call Lambda functions via API Gateway.

However, starting in 2024, RSS Feed Integration became available only with paid IFTTT Pro, so I was reluctantly paying the annual fee of $34.99.

GitHub:

Hatena Bookmark:

Current Architecture Diagram

Since I wasn't using IFTTT anywhere else, I really didn't want to continue paying the annual $34.99, so I completely migrated to an AWS serverless architecture this time.

The architecture uses EventBridge Scheduler to periodically check feeds and DynamoDB for read state management. Dependencies on external services have been eliminated, and processing is now completed entirely within AWS.

GitHub:

Hatena Bookmark:

Current Architecture

In the new architecture, the following components work together:

Periodic execution with EventBridge Scheduler

GitHub private feeds are checked every 5 minutes, and Hatena Bookmark favorites feeds every 15 minutes, executing the Lambda Subscriber functions shown below.

Lambda function responsibility separation

Each feed is separated into 2 Lambda functions:

Subscriber function: Feed retrieval and new item detection
- Retrieve RSS/Atom feeds and parse with rss-parser
- Manage read state with DynamoDB
- Call Notifier function if there are new items
Notifier function: Execute notification processing
- Filtering processing (GitHub only notifies specific events)
- Post to Mastodon
- Send notifications to Pushover (GitHub only)

Duplicate prevention with DynamoDB

Create tables for each feed
- GitHub: masutaka-feed-github-state
- Hatena Bookmark: masutaka-feed-hatebu-state
Set partition keys
- GitHub: Atom feed, each entry's id
- Hatena Bookmark: RSS 1.0 feed, each item's rdf:about
Set TTL to automatically delete old records after 30 days

Configuration management with SAM continues

As before, I use AWS SAM to manage the configuration of added components.

Environment variables continue to be managed with GitHub Actions Secrets/Variables, and automatic deployment occurs when commits are added to the main branch.

.github/workflows/deploy.yml

After the migration

Despite increased responsibilities, the code became unexpectedly cleaner
rss-parser was more convenient than expected - by just defining feed types like GitHubFeedItem and HatebuFeedItem, parsing became simple
- As a result, I was able to abandon HTML extraction using regular expressions
No longer need to pay IFTTT Pro's annual $34.99
- AWS costs stay within the free tier
Running error-free for about 2 weeks

Implemented with Claude Code

After starting to pay for IFTTT Pro, I had the concept in my head, but since it was essentially refactoring, I couldn't get motivated and left it alone.

Claude Code helped me overcome that lack of motivation, and I made great use of it.

Migration from JavaScript to TypeScript
- https://github.com/masutaka/masutaka-feed/pull/74
Migration from IFTTT Pro to AWS self-implementation
- https://github.com/masutaka/masutaka-feed/pull/77

💡 Each commit message in the pull requests contains Claude Code prompts.

Resource definitions in template.yaml are tedious to research, but Claude Code wrote them in one shot. Of course, I verified them afterwards.

EventBridge Schedulers definition
DynamoDB Tables definition
IAM Role settings for each resource
CloudWatch Alarm monitoring definitions

Conclusion

By self-implementing IFTTT Pro's feed notification feature with AWS serverless architecture, I was able to gain the following benefits:

Cost reduction: Annual fixed cost of $34.99 became essentially zero
Transparency gained: Full control over what items are added to feeds and what items have been marked as read
Enhanced monitoring: Can set up monitoring for feed subscriptions and detect failures immediately
Code optimization: Optimized feed parsing using rss-parser

Additionally, by utilizing Claude Code, I was able to significantly lower the motivation barrier for tasks like migrating from JavaScript to TypeScript and creating SAM templates.

I will continue to operate masutaka-feed at a low altitude going forward.

Example: https://github.com/masutaka.private.atom?token=xxxx ↩
Example: https://b.hatena.ne.jp/masutaka26/favorite.rss?key=xxxx ↩

Added llms.txt and llms-full.txt to My Hugo-built Website

Takashi Masuda — Sun, 18 May 2025 12:38:45 +0000

What is llms.txt?

llms.txt is a Markdown-formatted text file proposed to address the limitation that LLMs have small context windows and cannot process entire websites.

It was proposed on September 3, 2024, by Jeremy Howard of Answer.AI at https://llmstxt.org/. It is not defined in an RFC like robots.txt.

The format includes certain specifications such as the website name in an H1 section, a brief summary, and a list of links in H2 sections.
Example: https://llmstxt.org/llms.txt

There's also llms-full.txt, which contains all website information.
Example: https://developers.cloudflare.com/llms-full.txt

There are directory sites for llms.txt as well:

The llms.txt and llms-full.txt I Added

I've added both:

How to Configure in Hugo

The necessary work involves modifying or creating just three files:

config.toml (modify)
layouts/index.llms.txt (create new)
layouts/index.llmsfull.txt (create new)

config.toml

I added the following to config.toml:

Defining outputFormats for llms and llmsfull while adding them to the default value of outputs.home, which is ["html", "rss"].

[outputs]
  home = ["html", "rss", "llms", "llmsfull"]

[outputFormats.llms]
  baseName = "llms"
  isPlainText = true
  mediaType = "text/plain"
  rel = "alternate"
  root = true

[outputFormats.llmsfull]
  baseName = "llms-full"
  isPlainText = true
  mediaType = "text/plain"
  rel = "alternate"
  root = true

layouts/index.llms.txt

I created layouts/index.llms.txt as a template for llms.txt:

# {{ .Site.Title }}

> {{ .Site.Params.Description }}


## Articles
{{ $yearMonthGroups := slice -}}
{{ range where (where (sort (.Site.GetPage "/posts/").Pages "Date" "desc") "Draft" "ne" true) "Sitemap.Disable" "ne" true -}}
{{ $yearMonth := .Date.Format "2006/01" -}}
{{ if not (in $yearMonthGroups $yearMonth) }}
* {{ $yearMonth -}}
{{ $yearMonthGroups = $yearMonthGroups | append $yearMonth -}}
{{ end }}
    * [{{ .Title }}]({{ .Permalink }})
{{- end }}


## Others

{{- $baseURL := .Site.BaseURL | strings.TrimSuffix "/" }}

* [Device]({{ $baseURL }}/device/): 所有デバイス
* [History]({{ $baseURL }}/history/): このサイトの歴史
* [About]({{ $baseURL }}/about/): 自己紹介
* [Privacy Policy]({{ $baseURL }}/privacy/): 当サイトの広告、アフィリエイト、プライバシーポリシー

Since Hugo site structures can vary widely, this is just one example. My blog has both blog posts and other articles, and since other articles don't change much, I hardcoded them in the Others section.

layouts/index.llmsfull.txt

I created layouts/index.llmsfull.txt as a template for llms-full.txt:

# {{ .Site.Title }}

> {{ .Site.Params.Description }}


{{/* Articles */}}
{{ range where (where (sort (.Site.GetPage "/posts/").Pages "Date" "desc") "Draft" "ne" true) "Sitemap.Disable" "ne" true }}
--------------------------------------------------------------------------------
title: "{{ .Title }}"
date: "{{ .Date.Format "2006-01-02" }}"
--------------------------------------------------------------------------------
{{ replaceRE "{{<\\s*comment\\s*>}}(.|\n)*?{{<\\s*/comment\\s*>}}" "" .RawContent -}}
{{ end -}}


{{/* Others */}}
{{ range slice "device.md" "history.md" "about.md" "privacy.md" -}}
{{ with site.GetPage . -}}
--------------------------------------------------------------------------------
title: "{{ .Title }}"
lastmod: "{{ .Date.Format "2006-01-02" }}"
--------------------------------------------------------------------------------
{{ replaceRE "{{<\\s*comment\\s*>}}(.|\n)*?{{<\\s*/comment\\s*>}}" "" .RawContent -}}
{{ end -}}
{{ end -}}

I made the delimiter longer because some articles contained ---.

Also, I made sure comments like the following wouldn't be included in llms-full.txt:

{{<comment>}}
This is a Hugo comment. It won't be output as an HTML comment either.
{{</comment>}}

nginx Configuration

Since llms.txt and llms-full.txt were showing character encoding issues, I added the following to the server directive:

location ~ "^/llms(-full)?\.txt" {
    root /usr/share/nginx/html;
    charset UTF-8;
}

Conclusion

I added llms.txt and llms-full.txt on my Hugo-built blog:

Regardless of whether there's demand for it, I'm satisfied with the result.

As a side note, I initially found a method on Hugo Discourse that used resources.ExecuteAsTemplate in layouts/robots.txt to generate llms.txt. However, I decided not to use this approach since including llms.txt in robots.txt is not yet common practice.

Another side note: in the past, my blog was created by converting a single ChangeLog-formatted file into HTML using a tool called chalow. Creating llms-full.txt reminded me of those days. It feels like I've come full circle.

What We Did to Gain 3,000 GitHub Stars for the Liam Repository

Takashi Masuda — Mon, 21 Apr 2025 08:30:55 +0000

Recently, the Liam repository exceeded 3,000 stars just three months after its release. The repository continues to gain stars, alongside increases in traffic, forks, and external contributions.

These stars didn't accumulate naturally—they were the result of proactive strategies.

In this article, I'll share our thinking and the strategies we implemented to achieve 3,000 GitHub stars.

What is Liam ERD?

Liam ERD is the first product under the Liam brand, a tool that easily generates beautiful ER diagrams automatically from database schemas. It's released as open-source software with the goal of growing alongside the community.

Liam ERD

Automatically generates beautiful and easy-to-read ER diagrams from your database.

liambx.com

Setting 3,000 GitHub Stars as a KPI

We set 3,000 GitHub stars as our KPI for the following reasons:

We are currently developing a paid product in the database design space based on Liam ERD
We wanted to significantly expand recognition for the first product under the Liam brand
GitHub stars are a public metric that serves as a leading indicator of user trust¹

Strategies Found from Predecessors

Having set GitHub stars as our KPI, what specific actions should we take?

Throughout my career as a software engineer, I've developed OSS individually and created OSS repositories for companies, but I had never promoted a company's OSS. Also, blatant promotion isn't something I personally prefer.

I consulted Google and ChatGPT, but ultimately found an article featured on the Star History website.

🔗 The (Detailed & Creative) Playbook for Getting More GitHub Stars

"Writing the post I wish I found 6 months ago" was exactly the information I was looking for.

Strategies Implemented to Gain 3,000 GitHub Stars

Basically, I turned everything mentioned in the Star History article into actionable tasks and implemented the ones that were feasible for us.

Here are the specific strategies we implemented, with links included:

1. Preparation

Increasing traffic without proper repository preparation would be counterproductive. First, we focused on preparing the repository to welcome interested users.

Setting up the GitHub Repository for OSS

We set up the repository following the guidelines in the article below. We tried to include all GitHub recommendations and security measures.

Takashi Masuda for ROUTE06, Inc.

Jan 6 '25

Sharing the "OSS Publishing Tutorial" Created by ROUTE06, Inc.

#ospo #opensource #github

Comments

8 min read

Organizing the README.md

README.md is the face of the repository.

To make it intuitively understandable at first glance, we focused on:

Using attractive animated GIFs to instantly show what the ER diagrams look like
Creating a clear tagline that concisely summarizes the tool's features
Using colorful badges created with Shields.io to display the tool's status

Additionally, to encourage community participation, we included:

Links to contribution guidelines and roadmap
Visualization of contributors using contrib.rocks

After release, screenshots of the README.md were frequently shared on social media, confirming its role as the repository's face.

2. Directly Increasing GitHub Stars to 100

Before sharing on social media, we wanted to show that many people were already interested in the repository, so we aimed to reach 100 stars through direct strategies.

Sending Kickoff Messages to Friends and Acquaintances

I directly asked friends and acquaintances to star the repository via X (formerly Twitter) DMs and Slack.

Making the First Post on X After Exceeding 100 Stars

We had planned to post after getting a few dozen stars, but the response exceeded our expectations, so we posted after surpassing 100 stars.

https://x.com/liam_app/status/1881975247613923737

Here's what we focused on in this post:

Prepared a video that clearly demonstrates what the tool can do
Concisely introduced features in bullet points
Mentioned well-known relevant accounts
- React Flow quoted and reposted it²

As a result, we gained 41 reposts and approximately 30,000 views.

💡️ Although we are a Japanese team, all our X posts are in English. This is to avoid being perceived as a product only for Japanese users, which could limit its appeal in English-speaking regions. Based on our estimates, the majority of stars seem to come from users outside Japan.

3. Indirect Strategies After Exceeding 100 GitHub Stars

Creating Blog Content on the Service Website

We created content for our company blog, including direct or indirect introductions to Liam ERD, list articles, and knowledge-sharing pieces.

Example: Introducing Liam ERD - Liam ERD

Distributing Blog Content to Various Media

We cross-posted to dev.to, Hashnode, and Medium with canonical URLs set.

Example: Generate Beautiful and Interactive ER-Diagrams with Liam ERD - DEV Community

We posted slightly modified content on Reddit and HackerNoon. As a side note, you can't post to certain subreddits on Reddit without accumulating karma first. It's better to build up karma early.

Example: New Open-Source Tool Lets You Auto-Generate ER-Diagrams for Database Visualization | HackerNoon

We also posted a translated article on Zenn for the Japanese audience. This article helped generate our first +100 stars, but it resulted in Japan accounting for over 60% of stars by country, raising concerns about our initial hypothesis regarding the potential to be overlooked in English-speaking regions.

Generate Beautiful and Interactive ER Diagrams with Liam ERD - Zenn

Promoting on Various Sites and Newsletters

In addition to the sites mentioned in the Star History article, we researched other potential promotional sites. Except for Hacker News and Reddit, these were all new to me.

As of writing, we've been featured on:

Hacker News
- https://news.ycombinator.com/item?id=42789874
Reddit - r/coolgithubprojects
- https://www.reddit.com/r/coolgithubprojects/comments/1iza4q6/liam_erd_generates_beautiful_and_easytoread_er/
- This subreddit doesn't require karma and had a good response with 7 upvotes and 1K views
daily.dev
- https://dly.to/D8CwMwsw2Jb
- Unexpectedly good response with 211 upvotes, 2.5K views, 11 comments, generating our first +100 stars in the Japanese region
Gitroom
- https://gitlibrary.club/databases/1
CodeTriage
- https://www.codetriage.com/liam-hq/liam
Up For Grabs
- https://up-for-grabs.net/#/filters?names=563
- Not many, but generates continuous traffic
freestuff.dev
- https://freestuff.dev/alternative/liam-erd
Open Hub
- https://openhub.net/p/liam
G2
- https://www.g2.com/products/liam-erd
Dev Hunt
- https://devhunt.org/tool/liam-erd
- Paid, but they promoted us several times on X during the featured period
It's launched!
- https://itslaunched.com/product/liam-erd

To get featured in React Flow's Showcase, we mentioned them several times on X and posted about our blog article on X. Thankfully, they featured us quickly.

https://reactflow.dev/showcase

[Column] How We Researched Potential Promotional Sites

While still exploring, here's how we researched:

Used Ahrefs to check backlinks of competitors and similar products, adding sites that featured those products to our list of candidates
Searched directly using ChatGPT and Google
Sometimes found sites by chance during daily checks of Hacker News, Reddit, etc.
- For example, we found It's launched! through Hacker News' Show HN
Sometimes found sites through a chain of discoveries:
1. The Star History article mentioned earlier was originally a cross-post from this dev.to article
2. Read all articles by Livecycle on dev.to
3. Learned about Dev Hunt³ and added it to our candidates
4. Dev Hunt founder John Rush is a serial entrepreneur who creates products solving challenges like ours, and builds more products with his existing ones
5. Researched several of his products and added some to our candidates. Among them, https://osssoftware.org/ was particularly interesting in its small-scale approach

Introducing at Tech Conferences

So far only in Japan, but team members have introduced Liam ERD at several conferences.

Example: Findy Tools 1st Anniversary Celebration

Adding to GitHub awesome-lists Repositories

We submitted pull requests to relevant 'awesome list' repositories related to Liam ERD. The following repositories merged our requests:

Approaching Influencers

We directly reached out to influencers who introduce OSS projects:

Celebrating Milestones

We posted celebratory messages on X when we reached milestone numbers of stars:

200 stars
- https://x.com/liam_app/status/1882291797399101882
500 stars
- https://x.com/liam_app/status/1888786665231245525
1,000 stars
- https://x.com/liam_app/status/1896390308319080924
3,000 stars
- https://x.com/liam_app/status/1910494502873424353

Most Effective Strategies

daily.dev and X posts by influencers were particularly effective.

The most effective was @GithubProjects' X post in early April. This resulted in a #2 daily ranking on GitHub Trending, creating the following positive cycle:

Featured on GitHub Trending
Massive increase in Liam repository traffic and stars
Continued featuring on GitHub Trending

At this stage, we noticed an increase in spontaneous sharing without our involvement.

It's fair to say that "to increase stars, aim to be featured on GitHub Trending."

🔗 https://www.star-history.com/#liam-hq/liam&Date

Conclusion

I've shared the strategies we implemented to gain 3,000 GitHub stars for the Liam repository.

As a software engineer, I initially hesitated about actively promoting OSS, but changed my mindset, recognizing that good products don't always spread organically.

I'm truly grateful for the Star History article mentioned earlier. Fortunately, I had the opportunity to directly express my gratitude to the author, Zevi Reinitz⁴.

This article is just one example, so I can't guarantee that following these exact steps will lead to success. I hope it serves as a useful reference for someone.

Created an Emacs Lisp function to insert the title of a GitHub Issue/PR/Discussion URL

Takashi Masuda — Fri, 18 Apr 2025 09:43:02 +0000

On GitHub, when you paste Issue/PR/Discussion URLs into comments or descriptions, GitHub automatically renders the status, title, and number.

For example, if you write the following:

* https://github.com/masutaka/sandbox/issues/93
* https://github.com/masutaka/sandbox/issues/70
* https://github.com/masutaka/sandbox/pull/90
* https://github.com/masutaka/sandbox/discussions/91

It renders like this:

However, when writing in a plain text area or text editor, the URLs aren't automatically expanded, so you can't see the titles or statuses at a glance. This isn't a problem with just a few URLs, but it can become confusing when dealing with many.

Previously, I added comments manually like this, but it became tedious, so I created an Emacs Lisp function to automate the process.

* https://github.com/masutaka/sandbox/issues/93 <!-- Create test.rb --> (In Progress)
* https://github.com/masutaka/sandbox/issues/70 <!-- 2024/09 Sample Issue --> (Done)
* https://github.com/masutaka/sandbox/pull/90 <!-- Give CodeQL no running part2 -->
* https://github.com/masutaka/sandbox/discussions/91 <!-- 2025-02-05 ミーティングレポート -->

The Function I Created

🔗 ~/.emacs.d/init.el#L109-L152

(require 'cl-lib)
(require 'request)

(defun github-expand-link ()
  "Use the GitHub API to get the information and
insert a comment at the end of the current line in the following format:

- Issue URL <!-- Title --> (Done or In Progress)
- PR/Discussion URL <!-- Title -->"
  (interactive)
  (let ((url (thing-at-point 'url 'no-properties)))
    (if (not url)
        (message "[github-expand-link] No URL at point")
      (let* ((parsed-url (url-generic-parse-url url))
             (host (url-host parsed-url))
             (parts (split-string (url-filename parsed-url) "/" t)))
        (if (and (string-match-p "github\\.com$" host) (>= (length parts) 4))
            (let ((access-token (my-lisp-load "github-expand-link-token"))
                  (org (nth 0 parts))
                  (repo (nth 1 parts))
                  (type (nth 2 parts))
                  (number (nth 3 parts))
                  (type-alist '(("issues" . "issue") ("pull" . "pullRequest") ("discussions" . "discussion"))))
              (request
                "https://api.github.com/graphql"
                :type "POST"
                :headers `(("Authorization" . ,(concat "Bearer " access-token)))
                :data (json-encode `(("query" . ,(format "query { repository(owner: \"%s\", name: \"%s\") { %s(number: %d) { %s } } }"
                                                         (url-hexify-string org) (url-hexify-string repo)
                                                         (cdr (assoc type type-alist)) (string-to-number number)
                                                         (if (equal type "issues") "title state" "title")))))
                :parser 'json-read
                :sync t
                :success (cl-function
                          (lambda (&key data response &allow-other-keys)
                            (let* ((body (car (alist-get 'repository (alist-get 'data data))))
                                   (title (alist-get 'title body))
                                   (state (alist-get 'state body)))
                              (end-of-line)
                              (insert (if state
                                          (format " <!-- %s --> (%s)" title (if (equal "CLOSED" state) "Done" "In Progress"))
                                        (format " <!-- %s -->" title))))))
                :error (cl-function
                        (lambda (&key error-thrown response &allow-other-keys)
                          (message "[github-expand-link] Fail %S to POST %s"
                                   error-thrown (request-response-url response))))))
          (message "[github-expand-link] Not a valid GitHub Issue/PR/Discussion URL"))))))

Since there doesn't seem to be a GitHub REST API for retrieving Discussion information, I'm using the GraphQL API.

I try not to use many third-party packages, but I do like using request.el.

my-lisp-load is a function I introduced in 2016-05-06-2. If you create a PAT at https://github.com/settings/tokens and save it to ~/.emacs.d/spec/github-expand-link-token, you can load it with (my-lisp-load "github-expand-link-token"). If you want to reference Issues/PRs/Discussions in private repositories, set the PAT scope to repo.

I've assigned the keybinding ⌘-i to this function.

(define-key global-map (kbd "s-i") 'github-expand-link)

Conclusion

Being able to automatically insert titles, reminiscent of shell TAB completion, has proven more useful than I expected.

While writing this article, I decided to add Issue status as well, which required substantial changes.

I don't write Emacs Lisp frequently, so in the past, it was tedious to look things up via Google or check the official documentation. However, recently it's been convenient to learn about useful functions through ChatGPT and similar tools. This time, I learned about the alist-get function that way.

Visualizing Mastodon’s Data Schema with Liam ERD

Takashi Masuda — Wed, 09 Apr 2025 07:27:15 +0000

This post was originally written by Takafumi Endo, CEO of ROUTE06, Inc., and published on our company blog.

Mastodon stands as a prime example of how a decentralized social network can thrive under open-source principles. Rather than replicating the centralized models seen on major platforms, it empowers individuals to create their own servers—known as “instances”—all while remaining interconnected. This design ensures that each community can maintain its autonomy while still sharing a broader network.

The Mastodon Annual Report 2023, the latest annual report available at the time of writing, offers concrete data to support this growth. Over the past year, registered accounts rose by 38.5% to reach 8.8 million, and monthly active users totaled 1.56 million across 9,800 servers. Donations increased by 65%, thanks in part to community funding drives and a notable $100,000 contribution from Sujitech. On the product side, Mastodon introduced improvements in user onboarding, enhanced search functionality, and new mobile app features—leading to 1.87 million combined downloads on iOS and Android in 2023.

A key attraction of Mastodon is its “federated” design, which embraces a wide variety of communities. Each instance sets its own rules and fosters a distinct culture, giving users the freedom to join whichever environment resonates most with them—rather than adapting to a one-size-fits-all platform. In an era dominated by large tech companies, Mastodon’s personalized approach feels refreshingly different. Server administrators actively shape their local environment, and users themselves decide how they want to engage with others. This dynamic reflects the best qualities of the open-source mindset, where technology evolves through collaboration and direct user influence.

Looking ahead, Mastodon offers valuable insights into the future of social media. Its example shows how technological innovation and collective energy can come together to form a platform that is both cutting-edge and inclusive. Instead of entrusting everything to a single tech giant, people can build and sustain their own communities—and in doing so, shape the online spaces that matter to them most.

Demystifying Mastodon’s Data with Liam ERD

Our main goal with Liam ERD is to make complex databases easier to understand. Relying solely on SQL files and text-based documentation can quickly become confusing, so Liam ERD automatically generates visual diagrams of tables and relationships. This means you don’t have to sift through code line by line to see how everything fits together.

Using Liam ERD with Mastodon’s extensive database has been particularly rewarding. Mastodon has about a hundred tables that handle everything from user profiles to timelines and notifications. Rather than feeling overwhelmed, you can filter out irrelevant details and focus on what matters most—giving you a clearer picture of how Mastodon’s features interconnect.

We also made Liam ERD interactive. Instead of a static diagram, you can zoom, pan, and click on elements for more information. This hands-on approach turns the schema into a dynamic learning tool, letting you explore Mastodon’s architecture at your own pace.

While Mastodon’s schema is large, it is built on solid engineering practices: normalization, well-chosen data types, and foreign keys that maintain relational integrity. Seeing these best practices in action—especially at the scale of millions of users—can be far more illuminating than simply reading about them in a textbook.

Because Mastodon is open source, you can watch its schema evolve as new features are introduced or performance is optimized. For developers aiming to specialize in database engineering, Mastodon offers lessons in iterative design and scalability. Our goal with Liam ERD is to support that exploration, helping you dive deep into Mastodon’s data design without losing your way.

Generate ER diagrams effortlessly by entering a schema file URL. Ideal for visualizing, reviewing, and documenting schemas.

liambx.com

How Liam ERD Empowers OSS

Mastodon brings open-source values to life. Its code is fully public, contributions are welcomed worldwide, and the development process is transparent. This openness—together with its responsiveness to user feedback—reflects a strong culture of collaboration that aligns perfectly with Liam ERD’s mission to share knowledge and tools for everyone’s benefit.

Before Liam released their ERD, we asked Mastodon about featuring it, and we were especially pleased when Mastodon agreed to feature their ERD on our site. This underscores Mastodon’s commitment to transparency and its desire to help others learn from its platform. Such a spirit of shared resources and ideas drives supportive, innovative communities.

Mastodon’s user-centric decision-making also shows how agility and responsiveness can flourish when diverse voices have a say. The project tackles bugs, adds features, and evolves efficiently while remaining true to its vision—showcasing how shared ownership fosters sustained progress.

I believe many open-source projects have well-designed databases that often go underappreciated due to their lack of visibility. While text-based documentation can be overwhelming for potential contributors, visualizing the structure makes it much easier for maintainers, developers, and newcomers to understand how everything fits together.

We see Liam ERD as more than a diagramming tool—it’s a way for anyone, including non-developers, to understand a project’s data architecture and see where they can contribute. That approach matches the open-source principle that good ideas can come from anyone.

Making database structures easy to visualize also boosts inclusivity. When relationships are clearly outlined, anyone can jump in and say, “I know how to help.” Mastodon’s steady growth—fueled by contributors of all skill levels—demonstrates the impact of this openness.

liam-hq / liam

Automatically generates beautiful and easy-to-read ER diagrams from your database.

Open Source and Transparent Schemas

Mastodon’s robust database and Liam ERD’s visual approach complement each other naturally, both driven by the belief that sharing and accessibility accelerate progress. By showcasing Mastodon’s underlying structure, we aim to lower barriers and inspire people to learn, collaborate, and innovate.

Clarity and transparency in database design amplify a software project’s potential. Developers work more confidently when they can see a clear map, and open-source communities thrive when people learn from one another’s work. This blend of technical excellence and human-centered collaboration continues to propel software forward for anyone ready to join in.

Tuning Edge Animations in Reactflow for Optimal Performance

Takashi Masuda — Tue, 08 Apr 2025 04:41:16 +0000

This post was originally written by Junki Saito, and published on our company blog.

Liam ERD relies on the incredible capabilities of React Flow to visualize complex data models—like tables and relationships—on the web. We’re genuinely grateful for how React Flow enables rapid development and a beautiful user experience right out of the box. That said, when you’re working with truly massive datasets, you need to make sure your app still runs at top speed. In this post, I’ll walk you through how we tackled performance issues related to edge animations and the steps we took to keep everything running smoothly.

The Challenge: Animated Edges and Performance Bottlenecks

One of the standout features in React Flow is the effortless animation you can apply to edges. By simply toggling animated to true, you get a dashed-line effect that makes relationships feel alive. We loved this feature—it instantly added a sense of dynamic flow.

/**
 * This code is written in Stackblitz
 * @see https://stackblitz.com/edit/sb1-74jfdcqt?file=src%2FApp.tsx
 */
const initialNodes = [
  {
    id: '1',
    type: 'input',
    data: { label: 'Input Node' },
    position: { x: 250, y: 25 },
  },
  {
    id: '2',
    data: { label: 'Default Node' },
    position: { x: 100, y: 125 },
  },
  {
    id: '3',
    type: 'output',
    data: { label: 'Output Node' },
    position: { x: 250, y: 250 },
  },
];

const initialEdges = [
  {
    id: 'e1-2',
    source: '1',
    target: '2',
    animated: true
  },
  {
    id: 'e2-3',
    source: '2',
    target: '3',
    animated: false
  },
];

function App() {
  return (
    <ReactFlow
      nodes={initialNodes}
      edges={initialEdges}
    />
  );
}

The issue arose when we started rendering a huge number of edges for large ERDs, like in Mastodon, which can involve over 100 tables and countless relationships. We noticed a significant dip in responsiveness whenever we hovered over or dragged around nodes—some browsers handled it better than others, but overall, it was clear that the animations were holding back performance.

Identifying the Root Cause: The Culprit - stroke-dasharray

After digging in, we discovered that React Flow’s edge animations rely on the CSS property stroke-dasharray.

While it does create a neat dashed effect, it can seriously push your CPU when you have lots of SVG elements doing the same thing at once. Multiple user reports and bug threads confirmed that stroke-dasharray can be a major slowdown:

In our case, with hundreds of edges animated simultaneously, stroke-dasharray quickly became the main bottleneck.

The Goal: Retain Animation, Regain Smoothness

We still wanted the user experience of visually “flowing” edges. It’s a small detail that helps people see how tables and relationships link together in real time. But we absolutely had to solve the lag problem.

Our Solution: A Custom Animated Edge

To tackle this, we sidestepped the default animation approach in React Flow and crafted our own:

Bypassing React Flow's animated props: We disabled the library’s animated prop on edges to stop using stroke-dasharray.
Eliminating stroke-dasharray entirely: We cut it out for both animations and any default styling.
Implementing a Custom approach: We built a CustomEdge component that animates an SVG object along the edge path, as outlined in the React Flow docs. This gave us the same visual flair—minus the performance hit.

const PARTICLE_COUNT = 6
const ANIMATE_DURATION = 6

type Props = EdgeProps<RelationshipEdgeType>

export const RelationshipEdge: FC<Props> = ({
  data,
}) => {
  const [edgePath] = getBezierPath({
    ...
  })

  return (
    <>
      <BaseEdge
        id={id}
        path={edgePath}
      />
      {/* data.isHighlighted will be true if the edge should be highlighted. */}
      {data?.isHighlighted &&
        [...Array(PARTICLE_COUNT)].map((_, i) => (
          <ellipse
            key={`particle-${i}-${ANIMATE_DURATION}`}
            rx="5"
            ry="1.2"
            fill="url(#myGradient)"
          >
            {/* The <animateMotion> element defines how an element moves along a motion path.  */}
            <animateMotion
              begin={`${i * (ANIMATE_DURATION / PARTICLE_COUNT)}s`}
              dur={`${ANIMATE_DURATION}s`}
              repeatCount="indefinite"
              rotate="auto"
              path={edgePath}
              calcMode="spline"
              keySplines="0.42, 0, 0.58, 1.0"
            />
          </ellipse>
        ))}
    </>
  )
}

By implementing these three approaches, the appearance changed from looking like Before gif image to looking like After gif image.

Before	After

You can see exactly how we did it in our Pull Request:

🚸 Add animated particles to highlighted relationship edges #367

junkisai posted on Dec 24, 2024

Summary

Drawing multiple strokes with stroke-dasharray specified causes performance degradation, especially in Safari browser.

Therefore, I stopped using stroke-dasharray. Additionally, since stroke-dasharray is also used when 'animated' is set to true in Edge, I made sure that 'animated' is always set to false.

Furthermore, since setting 'animated' to false made it difficult to visually distinguish the flow of Edges, I used animateMotion instead to express Edge animations.

Before	After

View on GitHub

Results: Measuring the Improvement

We ran before-and-after tests using Chrome DevTools to measure frame drops. Our test steps:

Hover over the “Accounts” table node in Mastodon’s ERD: Mastodon’s schema.rb
Wait 3 seconds, then remove the hover.

Demonstration of actions for comparison.

Findings:

Before: We saw consistent frame drops of around 5 frames at a time.
After: Frame drops went down to 2–3 frames at a time.

Not surprisingly, our changes made the overall experience smoother and more responsive—no more choppy dragging or sluggish hover states.

Optimizing React Flow for Scalable Products

By digging into React Flow’s edge animation logic and crafting a custom approach, we found a sweet spot between visual polish and raw performance. Disabling stroke-dasharray and opting for a more controlled animation model let us keep the dynamic look of animated edges while ensuring that our largest ERDs run like butter. We hope this helps anyone else wrestling with performance challenges on React Flow—you can absolutely keep those animations, as long as you give them some thoughtful tweaks.

Liam ERD required a highly scalable node-based engine to efficiently render large, interconnected schemas. That drove our choice of React Flow, which effortlessly manages 100+ tables and hundreds of edges while allowing the fine-grained control we need for selective highlighting and custom animations. Since Liam ERD relies on type-safe schema transformations, React Flow’s robust TypeScript support proved indispensable. Its performance tuning capabilities, including the custom animation optimizations we described, make it ideally suited for complex database diagrams. If your product demands large-scale interactive data modeling or specialized node behavior, React Flow is an excellent foundation to build upon.

For more insights into Liam ERD and what we’ve been working on, feel free to check out our introduction post:

Introducing Liam ERD - Liam ERD

Discover Liam ERD, a modern tool for effortlessly auto-generating interactive, readable ER diagrams from database schemas. Perfect for team collaborat...

liambx.com