Turbo Internals - Setting Up the Codebase

April 13, 2022   • turbo-internals hotwire

Recently I’ve been reading the source code of the Turbo library. The code is well-written and easy-to-understand. Reading it has been a fun exercise, not just to learn the internals of Turbo, but also how experts like Sam Stephenson write their JavaScript. I took a lot of notes while reading the code, and I will share them in future posts.

This post explains how to download and set up the codebase so you can easily debug and step through it in the browser.

Step 1: Get the Source Code

Before diving into the codebase, you first need to get the working source code on your development machine. For this, clone the Github repository.

git clone https://github.com/hotwired/turbo.git

Step 2: Compile the Source Code

First, download esbuild, an extremely fast JavaScript and CSS bundler and minifier that will make you forget everything about Webpack or any complicated TypeScript build setups you’ve used in the past. Once you’ve tried esbuild, there’s no going back.

yarn global add esbuild

Then, build the source using the following command:

esbuild --bundle src/index.ts --outdir=public/js --sourcemap

This compiles the source code, which is written in TypeScript to a single file named index.js in the public/js directory. Note that we used the --sourcemap option so we can access the original source code while debugging in the developer tools.

Step 3: Add the JavaScript to an HTML Page

Once you have the JavaScript file, use it in an HTML file in the same public directory. I also added another HTML page (/pages/about) so we can see what happens when you click a Turbo link.

touch public/index.html
touch public/pages/about.html

Add the following content in those files.

# public/index.html
<!-- public/index.html -->
<!doctype html>
<html>
<head>
    <meta charset=utf-8>
    <title>Home</title>
    <script src="/js/index.js"></script>
</head>
<body>

<h1>Hotwire + Stimulus</h1>
  
<a href="/pages/about">About</a>

</body>
</html>


<!-- public/pages/about.html -->

<!doctype html>
<html>
<head>
    <meta charset=utf-8>
    <title>About</title>
    <script src="/js/index.js"></script>
</head>
<body>

<h1>About</h1>

</body>
</html>

Step 4: Launch the Web Server

We are going to use the simple, zero-configuration command-line static http-server. First, install it using either yarn or npm:

npm install --global http-server

Then, launch the server using this command from the root directory.

http-server

Now open the URL in the browser, and open the developer tools. Under the source tab, search for a file named src/index.ts, and put a breakpoint on the start method. Now reload the page.

That’s it! You are all set to debug the source code of Turbo. In the next post, we will try to understand what happens when you click a Turbo link.

Tip: You can add the following scripts in the package.json to simplify the build. The second command tells esbuild to watch and re-build when the source code changes.

"scripts": {
	"esbuild": "esbuild --bundle src/index.ts --outdir=public/js --sourcemap",
	"eswatch": "esbuild --bundle src/index.ts --outdir=public/js --sourcemap --watch",
}

Now you can simply run the command yarn esbuild or yarn eswatch and esbuild will do its magic.