Aymeric Beaumet | Posts, Talks & Projects

Developers, please nurture your coding experience

Fri, 19 Aug 2022 00:00:00 GMT

I see writing code as an art. An art we would each approach from a different perspective, playing with the tools we are being offered. We all evolve at a different level of the stack. And yet, we all conceptually work very similarly: editing some code in a form or another to make the machines behave as we expect.

What is the only interface between you and the code you write? Your machine. Your workstation. Your work environment. Your workflow. There are different ways to name it, but ultimately that’s what enabling you to write code.

I believe taking complete ownership of one’s environment is a key attribute of becoming a better engineer. Some people would argue it brings a productivity boost. While that might be true, I think the main reason to get to know your environment is to move potential obstacles out of the way. To let your thoughts flow efficiently from your brain to code. The productivity boost is a consequence, not a mean in itself.

We should all get to know our environments. Caring about it is not only beneficial for you. It is also beneficial for your coworkers and any person you work with. Not only that, but it will give you a better intuition of what represents a good or bad environment, and that always comes handy.

The good news is: your journey has already begun. You already have a work environment. You already took inspiration from your peers. You are already using tools developed by people that happen to be improving their environment in a way that suits your needs. So where should you go next?

Pursue your journey

I usually start by introspecting my workflow to identify pain points. It is often harder said than done, especially because our brain is excellent at accepting a current situation as long as we’ve been exposed to it long enough. And that’s still the case even if there are significant improvements waiting for us down the road.

Introspection could happen in the form of self-assessing questions like:

what are my most frequent tasks?
where am I wasting my time?
what are the most tedious tasks I have to do on a regular basis?
which inconsistencies can I find in my workflow?
what is slowing me down?

All of these questions will help you find potential directions for improvements.

While working on this article, I was wondering about what would be the fundamental concepts if I were to distillate my mindset into key points. I found 5 of them:

Keep your stack simple. When you can, choose simplicity over complexity. Find the smallest set of tools required to do the job and consolidate your workflow around them. Remove the tools you don’t need.
Don’t let your stack get obsolete. Challenge your existing stack on a regular basis. Make sure you keep your tools up-to-date. Do not miss out on the latest opportunities brought by modern tooling.
Integrate your tools together. Having a small set of tools that you master and make them talk to each other is immensely useful. The Unix philosophy applies here. By design, it is easier to follow this principle when working in a terminal.
Practice is essential. Getting to know your tooling is all down to practice. Learn the shortcuts. Learn how they behave. You need to deeply understand these tools, so they become an extension of yourself.
Stability is key. This is a never ending journey, and you should always keep digging for ways to improve. But also know when to pause. Your habits and muscular memory will be impacted if you change your stack too often.

Applying these concepts has been my rock over all these years. Sticking to this will slowly but steadily bring you to a better place.

Concrete examples

I’ve started to code back in 2005. I was using Windows XP, Firefox, and Notepad++ at the time. At that time the concept of productivity didn’t even cross my mind. Over the years, I’ve gathered experiences in various environments (mainly Linux and macOS). I want to talk about a few situations which I’ve identified as problematic and improved in my workflow.

The first one I want to mention is about my keyboard. What is slowing me down? Well, I found myself doing a lot of typos when typing. I had to stop my flow, correct the error, and start typing again. So I looked it up and tried to find solutions. The first thing that comes up on the topic is to learn how to touch type (I couldn’t recommend keybr.com enough). But then my brain was tickled: if I’m ready to spend time to improve my typing skills, is there more I could do? It turns out I could, and long story short, I ultimately settled on learning to touch type with the Colemak layout. It’s been so since 2015, and I couldn’t be happier.

The second one is about the feedback loop when working on Go and Rust projects. Where am I wasting my time? I was used to working with the Node.js ecosystem (jest, nodemon, webpack, etc) that natively integrates many ways to optimize the feedback loop (watching, reloading, hot-reloading, etc). I was manually restarting my programs and tests when working on Go and Rust projects, so I tried to find a way to replicate this. I have currently settled on using watchexec that is a general purpose watcher. And I’ve aliased it to w to make it convenient to use.

The third one is my shell. What are my most frequent tasks? Well that is a software I’m using all day long, so I have high performance expectation. I want it to be blazingly fast, and it was not the case. Startup time as well as printing the prompt was slow. A basic shell is actually fast by default. Just try for yourself: start zsh without loading the configuration files to see how fast it is. I didn’t want to compromise on a rich prompt, but on the other hand, my shell was slow. So what to do? I began with an empty configuration file and only added the bits I needed. My ~/.zshrc is 200 lines of code and loading 4 plugins. I have also made the switch to powerlevel10k. And I’m now satisfied with my shell user experience.

The last one is a story happening at my current job. I’m working for REKKI as a Lead Platform Engineer, and part of my team’s mission is to design and improve the Developer Experience. In doing so, I’m letting the vision shared in this blog post infuse in my every day work. What are the most tedious tasks I have to do on a regular basis? Well, setting up the stack for all the engineers working at REKKI was getting more and more painful. So we’ve released an internal CLI that does this for us, installed by default on all the engineers machines.

Each of those examples could be a blog post in itself. And I could continue over and over on other topics: learning how to debug and instrument my code, learning how not to use the mouse, learning how to master my editor (nvim/init.lua), learning how to use snippets, learning how to take notes efficiently, learning how to create impactful slides, etc. But it’s not the point.

The point here is to show you the mindset: identify issues, find which one would have the biggest impact if fixed, and address them.

Final words

We’ve seen why spending time on your work environment is important, along with some practical advices to help you shape it according to your own needs. We’ve also looked at some examples of how I applied these advices to improve my workflow over the past few years.

This is in the end a very personal experience, and is all about getting to know yourself. Introspection is key here: what works for you might not work for someone else, and vice versa. This is your journey, and I hope this post inspired you to revisit your work environment. I’d love to hear how you improved your workflow.

Give it time, and you will be rewarded.

Faster git clones with sparse checkouts

Sat, 23 Jul 2022 00:00:00 GMT

We at REKKI are working on a monorepo that contains all the backend Go code for most of our services and jobs. As time goes by and the size of this repository grows, the time it takes for an initial clone becomes noticeable. While this is not really a problem on the engineers’ workstations as they operate statefully, it impacts stateless systems that have to download the codebase regularly: like CIs, CDs, or even our in-house CLI.

Our CLI sometimes needs to pull a fresh version of a specific commit from the Go codebase to perform beta updates when our engineers request it (e.g.: to test new features that are not yet released in the stable version). Cloning the Go monorepo every time they want to install a beta update is not an option, as it takes more than a minute on a good connection.

Shallow clones

The first approach you often take in a situation like this is to shallow clone. While a default clone will fetch all the commits and all the blob objects for the branch you track (by default master/main), a shallow clone will only fetch the blob objects for a subset of these commits, thus resulting in faster clone times.

That is very common in the world of CIs. For example, both GitHub Actions and Travis CI do it by default.

One way you’d do a shallow clone is by specifying the --depth=<n> flag to the git clone command, hence limiting the number of commits to pull starting from the HEAD:

# fetch the latest commit
git clone --depth=1 git@github.com:rekki/go.git

Another way to shallow clone it is to specify a start date instead of a number of commits. This is possible via the --shallow-since=<date> flag with either an absolute or a relative date:

# fetch the last day of commits
git clone --shallow-since='1 day' git@github.com:rekki/go.git

While shallow clones work well in some contexts, they fall short by downloading all the blob objects in the working tree for the given commits. So even specifying a depth of 1 results in non-negligible clone times for some repositories (in the case of our Go monorepo, this still takes 30 seconds).

Sparse checkouts

Another way to reduce the amount of downloaded data is to use sparse checkouts. Sparse checkouts solve that problem by allowing to partially checkout a working tree. While shallow clones give you control over the commits you want to fetch, sparse checkouts will enable you to specify the blob objects you wish to fetch.

While sparse checkouts exist since git 2.25.0, they are still considered experimental. It is unlikely that the feature will be removed in the future, but breaking changes might happen in both its implementation and its usage.

You can either specify a list of directories (in what’s called cone mode) or a list of patterns (ala .gitignore). The manual recommends using the cone mode for performance reasons.

Leveraging sparse checkouts allows you only to fetch the blob objects you need for the task you want to perform. In our case, we wanted only to clone the files required to build our CLI. This is how we did it:

git clone --filter=blob:none --no-checkout git@github.com:rekki/go.git
cd go
git sparse-checkout set --cone go.mod go.sum cmd/rekki-cli pkg/rekki/errors
git checkout master

Let’s explain step by step:

git clone: like a typical clone, but with 2 additional flags:
- --filter=blob:none: instructs not to fetch any blob object
- --no-checkout: instructs not to automatically checkout HEAD
git sparse-checkout set: enables the sparse checkout settings and specifies which files should be checked out. Change this line to whatever works for you.
git checkout master: checkouts the actual branch or commit (in this case, the master branch) and fetches the objects matching the sparse patterns.

You can easily adapt these commands to your use cases.

This approach allowed us to reduce the end-to-end time to clone to less than 5 seconds. We are satisfied with that number, and we know that time will only grow proportionally to the size of the code required to build the CLI (and nothing else). So it should stay fast for the foreseeable future.

Conclusion

Using sparse checkouts is a bit more involved in the commands you have to execute, but it allows for more control over the files you download on your local filesystem. You don’t always need the entirety of a git repository, and sparse checkouts allow you to pick what you need granularly.

Give it a try the next time you find yourself in a situation where a git clone takes too long. What use case do you have in mind? Leave a comment with your ideas below.

Prevent chromedp Chromium zombie processes from stacking

Sat, 13 Feb 2021 00:00:00 GMT

I have recently been playing with chromedp. Chromedp is a Go library that enables you to control a Chromium browser programmatically. This can be used for different tasks: from testing to scraping. I have some memories of implementing a similar program in Node.js, and I was pleased to leverage a strongly typed language for the job.

I was able to quickly start experimenting by following the examples and browsing the documentation. For the record, this is what the chromedp hello world looks like:

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	if err := chromedp.Run(
		ctx,
		chromedp.Navigate("https://github.com"),
	); err != nil {
		panic(err)
	}
}

The problem

Not so long after I started getting results, I suddenly heard my MacBook Pro fans running crazy. Similar to what’s happening when a brew install is not going as expected, and you feel like you are recompiling gcc from scratch. This was accompanied by a weirdly unpleasant gentle warmth on my hands and an increasing slowness on the macOS UI.

A quick look at the activity monitor revealed that the Chromium processes were not terminated as expected. They were also using a lot of RAM, and forced my computer to swap (hence the perceived slowness).

Running pkill Chromium got me out of trouble. But now remains the question: how to prevent this from happening in the future? A quick search on Google led me to the chromedp issue tracker, were several resolved issues are reporting this very problem. They were all closed, and I didn’t have the same symptoms, so I opened a new one to keep track of what I was facing.

TLDR: if you are looking for the solution, jump to the end of this post.

The quick fix

This problem will at some point be fixed upstream, but in the meantime I was looking for a temporary solution that would prevent the zombie processes from stacking (and eating my RAM). As it happens, the Chromium processes are spawned with the same user as the Go process. That means it should theoratically be possible (permission wise) to kill them from within the Go process right before it dies. I quickly tried to confirm this theory with the following code:

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer func() {
		cancel()
		if _, err := exec.Command("pkill", "Chromium").Output(); err != nil {
			log.Println("[warn] Failed to kill Chromium processes", err)
		}
	}()

	// ...
}

It is not as accurate as I would like it to be. All the Chromium processes on my machine (whose my user has rights on) would die, but this works. That being said, I’m not using Chromium as my primary browser, so I’m not really impacted. But then came the time to write this blog post, and I was sure at some point someone would face this issue and would also be using Chromium as its primary browser. So I started digging.

Going down the rabbit hole

As it turns out, man pkill gives us some interesting leads to explore. pkill (and pgrep for that matters, as they share most of their options) does support a flag allowing to restrict the processes receiving the signal to only the descendants of a specific PID (or said otherwise: all the processes whose parent is PID). This is achieved by providing the -P <PID> flag.

Once the code is adjusted to leverage the os.Getpid() function, only the Chromium processes started by the Go process will be killed:

_, err := exec.Command("pkill", "-P", strconv.Itoa(os.Getpid()), "Chromium").Output()

Or so I thought, this doesn’t work. As it turns out, the Chrome processes are not directly attached to the Go process as there are intermediate forks. So trying to match the parent process will not behave as you would expect.

While looking at the activity monitor, I noticed there was something else than the process ID (PID) mentioned: the process group ID (PGID). I was not sure what this was about. A quick look at the Wikipedia page reads:

In a POSIX-conformant operating system, a process group denotes a collection of one or more processes. Among other things, a process group is used to control the distribution of a signal; when a signal is directed to a process group, the signal is delivered to each process that is a member of the group.

It felt like this was one way to go, so I decided to dig this whole process group concept. Reading man ps helped me craft these two commands:

ps -o pid,pgid,command: which lists all the processes on the system, along with their PID, PGID, and the full command
ps -g <PGID>: which lists all the processes belonging to a specific process group ID

By using the first command, I found my Go process PGID (46499), and by using the second one I was able to list all of the processes in this group:

$ ps -g 46499
  PID TTY           TIME CMD
46499 ttys001    0:00.77 go run .
46518 ttys001    0:38.43 /var/folders/dg/3zgc8tkd0wg7d0zc0mst6jc00000gn/T/go-build917574381/b001/exe/scraper
46520 ttys001    0:01.72 /Applications/Chromium.app/Contents/MacOS/Chromium --disable-popup-blocking --safebr
46521 ttys001    0:00.80 /Applications/Chromium.app/Contents/Frameworks/Chromium Framework.framework/Versions
46522 ttys001    0:08.18 /Applications/Chromium.app/Contents/Frameworks/Chromium Framework.framework/Versions

This lists all the processes belonging to the Go process group (including Chromium’s). We are getting close to what we want. As it turns out, pkill also supports the -g flag (with the same semantic). So changing the code as follows should behave as expected:

_, err := exec.Command("pkill", "-g", strconv.Itoa(os.Getpid()), "Chromium").Output()

But it doesn’t. If you look carefully at the ps command above, you can see the actual scraper process, but above it is the go run . process, which is the process that created the group. As we can see, the process group ID is the PID of the process that created the group. So we should be careful to use the go run PID instead. In Go, you can get the PID of the parent process with os.Getppid(), which gives us:

_, err := exec.Command("pkill", "-g", strconv.Itoa(os.Getppid()), "Chromium").Output()

Does it work? Yes, finally! Well, it works when we go run ., but what happens when we go build and directly run the binary? Well, it’s not working. The reason is that the process group is no longer the one created by go run, but the one created by the binary itself as we run it directly. So we need to account for that when we try to guess the PGID from the code.

An easy solution is to try to pkill both for the current pid and the parent pid. At least one of them will be the process group ID. So as long as they don’t both fail, it means we have succeeded to kill all the zombie processes:

_, errA := exec.Command("pkill", "-g", strconv.Itoa(os.Getppid()), "Chromium").Output()
_, errB := exec.Command("pkill", "-g", strconv.Itoa(os.Getpid()), "Chromium").Output()

This works. But I don’t find this elegant as we expect half of the pkill commands to fail during a normal execution process. Can we take it one step further? Let’s have a look at man pkill:

-g pgrp     Restrict matches to processes with a process group ID in the comma-separated list
            pgrp.  The value zero is taken to mean the process group ID of the running pgrep
            or pkill command.

Reading this teaches us we could pass a comma-separated list of PID to -g, which enables to only call pkill once by passing both the PGID and the PID at the same time. But the second part of the description is much more interesting: by passing -g 0 we ask pkill to infer for us what is the current process group ID. That greatly simplifies the code by moving this responsibility out of Go.

The solution

By applying this to our piece of code, we reach this solution:

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer func() {
		cancel()
		// Prevent Chromium processes from hanging
		if _, err := exec.Command("pkill", "-g", "0", "Chromium").Output(); err != nil {
			log.Println("[warn] Failed to kill Chromium processes", err)
		}
	}()

	// ...
}

This does exactly what we want: it kills all the Chromium processes that have been started by the Go process without impacting any other Chromium process that would be running on your machine. This is simple, elegant, and works on all POSIX systems. It also has the advantage of being transposable to any other stack you use. Bingo!

Conclusion

You might be wondering: was it worth digging all the way through considering you already had a working solution from the get-go? That’s a good point. Well, first it was not working the way I expected it to. And second, I strongly believe our knowledge is always (and will always be) shallow, which makes me strive to take the time to dig deeper whenever I have the opportunity.

It is enjoyable how sometimes a simple problem will challenge you on something you thought was well outside your comfort zone.

Automatic Persisted Queries: why does it matter?

Tue, 20 Nov 2018 00:00:00 GMT

GraphQL is not to be presented anymore. One main drawback though in comparison to REST is the upstream bandwidth cost can become significant as the number of queries increases.

Automatic Persisted Queries aims at addressing this problem by allowing to cache the queries server-side. They can then be queried again through a unique identifier sent by the backend.

Unfortunately this talk was not recorded, but you can find the slides below.

Resilience: why, how, what?

Thu, 27 Sep 2018 00:00:00 GMT

We live in a world critically relying on a growing mass of information systems: whether it be for APIs, automation, synchronizing services, or any other server-side operation. But how do these systems react in case of failure?

As a back-end engineer, it is your job to implement a resilient system. Through this talk, we will look into some erroneous Node.js implementations and see how we can articulate coherent strategies to solve these issues.

This talk was given in French. The slides are in English.

Behold z, the unsung jewel that rethinks shell navigation

Wed, 14 Feb 2018 00:00:00 GMT

I spend a fair amount of time wandering around in the terminal. The chances are that you are too since you dared to open this story. My daily activities led me to contribute to various kinds of projects (professional, personal and open-source). For my sanity, I tend to follow strict rules to organize my workspace, which helps me keep things tidied up and easily reachable. Or so I thought.

I decided to arrange my projects by following the Go philosophy: make the arborescence mirrors the urls where they are reachable. e.g., ~/Workspace/src/github.com/aymericbeaumet/dotfiles would contain the project dotfiles owned by @aymericbeaumet and accessible at github.com. That’s great, but I am now facing a complex directory structure tedious to navigate quickly. Making it, in the end, harder to access the resources I need.

$ pwd
/Users/aymericbeaumet/Workspace/src/github.com/brigad/back-end

Nobody wants to manually deal with this.

Remembering and typing the location of each project (even while leveraging autocomplete) is time-consuming. Creating shell aliases is not scalable. Instead, I would like to rely on the pseudo-unicity of each project name to find it among all the directories on my computer.

z?

Several tools exist to tackle this problem. My favorite is z. It follows the Unix philosophy by being small, focused and interoperable. z allows jumping around swiftly, automatically learning from your habits. The entries are ranked based on the frecency at which you access the directories.

Let’s walk through the basics of this tool. Below is how I advise to install it for Zsh on macOS (the install process should be similar for other shells and operating systems):

$ brew install z
$ echo "source '$(brew --prefix z)/etc/profile.d/z.sh'" >> ~/.zshenv

Install z for Zsh on macOS.

Note how installing z is not enough to start using it. You have to source z.sh at the beginning of each shell session to activate it. The ~/.zshenv configuration file is appropriate as Zsh loads it in most circumstances, making the tool accessible in a wide-variety of contexts (terminals, editors, IDEs, scripts, etc.).

Let’s play

Once the install and setup are complete: start a new shell session, cd through some folders and execute z to confirm it has been accurately tracking your activity:

$ z | sort -rn | head -3
5331.72    /Users/aymericbeaumet/Workspace/src/github.com/brigad/back-end
637.255    /Users/aymericbeaumet/Workspace/src/github.com/brigad/ops
386.198 /Users/aymericbeaumet/.config/dotfiles

Top 3 directories based on frecency.

As shown above, I spend quite some time navigating through Brigad projects, but it seems I also often access my dotfiles to tweak some configuration. The ranking score is volatile, and one could observe significant changes in a brief amount of time.

Now that z has accumulated some knowledge try it by navigating to one of the tracked folders. Navigating is as simple as executing the z command followed by the directory name:

$ z dotfiles
$ pwd
/Users/aymericbeaumet/.config/dotfiles

Navigating by matching with a whole directory name.

As a matter of facts, I do prefer to leverage partial matching (imagine ** surrounding your search pattern) to type fewer characters. Hence, z dot is valid and should produce a similar behavior as z dotfiles (modulo possible name collisions, but you get the idea). This works because z relies on regular expressions. For example, the snippet below will navigate to the directory ending with the letters “tmp” (with the highest score):

$ z tmp$
$ pwd
/private/tmp

Navigating by matching with a regular expression.

Neat right? I guess you start seeing the possibilities of this tool. And we have only scratched the surface of its capabilities. I suggest you dive in its documentation to get an idea of its full potential. Features such as autocomplete, subdirectories matching, consecutive matching, etc. are a game changer.

Conclusion

z is tremendous. This tool saves me a non-trivial amount of time every single day. When one starts relying on it, there is no going back. And I hope it’s going to fit your workflow as well as mine.

I would be grateful to hear any of your time-saving tricks. Feel free to share your experiences!

Properly shim AngularJS applications using Browserify

Sun, 12 Oct 2014 00:00:00 GMT

Edit (March 5th 2015): the frontend community has evolved in the last few months and tends to be less hostile to the CommonsJS style (e.g.: Angular is now available on npm). This article has been rewritten accordingly.

AngularJS is a frontend framework developed by folks at Google. It allows to build advanced web applications in a modular way by splitting the code base into small components. This brings a lot of advantages like a clean separation of concerns and an easier testability.

Browserify is a tool which allows to benefit from the CommonJS modules in theoretically any JavaScript environments. Given an entry point, it computes a dependency tree, resolves it and produces a single output file. By consuming the package.json, Browserify enables to require node_modules in the build. This allows to rely on npm as a package manager for frontend dependencies, where Bower or Component would have been usually used.

When I first heard about Browserify, I immediately thought the modularity it brings would be really nice to build AngularJS applications. And it actually is. However they are not a perfect match by now, and some drawbacks need to be fixed.

This article presents a solution to structure an AngularJS application using Browserify. It covers the use of non-CommonJS modules as dependencies.

A sample application

Let’s consider a sample application which sets an entry in the local storage, and uses it to react differently whether it’s the first time a user is loading the page. It will be used as a support to identify the trouble cases and detail how to tackle them. So create an empty folder and let’s get started!

First, create an app.js file which will be the entry point:

var angular = require("angular");
var app = angular.module("app", [require("angular-local-storage")]);

app.run(function (localStorageService) {
	if (!localStorageService.get("lastVisit")) {
		angular.element("body").text("Hello stranger!");
	} else {
		angular.element("body").text("Welcome back!");
	}
	localStorageService.set("lastVisit", Date.now());
});

Neat, isn’t it? If you come from a Node.js background I’m sure you do like it.

Now let’s generate the package.json:

npm init
npm install --save angular angular-local-storage jquery
npm install -D browserify

Then compile the application:

./node_modules/.bin/browserify app.js -o bundle.js

And finally create a basic index.html to load it:

<html>
	<head>
		<script src="bundle.js"></script>
	</head>
	<body ng-app="app"></body>
</html>

Pretty simple huh? But as you might expect, this doesn’t work. Open index.html in a web browser and take a look at the console to find a nice JavaScript error.

Explanations

There are several issues occurring here.

Modules not defining an entry point

When a module is required, Browserify looks in the node_modules folder to find its package.json and loads it. Browserify expects it to have a main property which contains the relative path to the file which should be loaded.

It is usual that this property is missing, that it points to the wrong file or that the package.json itself is missing. In such case, you can override the file to load in the own project’s package.json:

{
	"browser": {
		"angular": "./node_modules/angular/angular.js",
		"angular-local-storage": "./node_modules/angular-local-storage/dist/angular-local-storage.js"
	}
}

Modules not properly exporting their content

When Browserify requires the file indicated by the main property in the module’s package.json, it is usual that this file does not properly export its content in the CommonJS style. Also, we expect AngularJS modules to export their names so that we could directly require them in our AngularJS modules definitions.

To this end, browserify-shim can be used.

First install it:

npm install -D browserify-shim

Then, update the package.json:

{
	"browserify-shim": {
		"angular": {
			"exports": "angular"
		},
		"angular-local-storage": {
			"exports": "angular.module('LocalStorageModule').name"
		}
	},
	"browserify": {
		"transform": ["browserify-shim"]
	}
}

angular exports the global variable angular
angular-local-storage exports its AngularJS module name LocalStorageModule

Modules fetching their dependencies on the global context

Some frontend modules relies on the fact their dependencies will be exposed on the global object (generally the window object in most browsers). This is an anti-pattern of the CommonJS architecture which favors separation of concerns.

For example, AngularJS expects jQuery to be exposed at the window.jQuery property.

One solution is to wrap the module into a function which exposes a global object with the appropriate properties. Hopefully, this could also easily done via browserify-shim (see above for the installation).

Then, update the package.json:

{
	"browserify-shim": {
		"angular": {
			"depends": "jquery:jQuery"
		},
		"angular-local-storage": {
			"depends": "angular"
		}
	}
}

angular will be provided the jquery module on a fake window object at the property jQuery
angular-local-storage will be provided the angular module the same way

Wrap up

You should have added the following content to your package.json:

{
	"browser": {
		"angular": "./node_modules/angular/angular.js",
		"angular-local-storage": "./node_modules/angular-local-storage/dist/angular-local-storage.js"
	},
	"browserify-shim": {
		"angular": {
			"depends": "jquery:jQuery",
			"exports": "angular"
		},
		"angular-local-storage": {
			"depends": "angular",
			"exports": "angular.module('LocalStorageModule').name"
		}
	},
	"browserify": {
		"transform": ["browserify-shim"]
	}
}

Once you’ve made those corrections, you should be able to compile and run the sample application:

./node_modules/.bin/browserify app.js -o bundle.js

Check it really works by opening index.html.

A working example can be found attached to this post.

Side notes

Some related facts which can save you time when dealing with Browserify:

modules not published to npm can be installed by giving their git repository URL: npm install git+https://github.com/angular-ui/ui-router.git. Note that it is also possible to directly pass a GitHub repository: npm install angular-ui/ui-router. A version can be specified by appending #tag. See the documentation for more information
modules not containing a package.json cannot be installed using npm (even by directly providing a git repository). To tackle this issue, a third party installer like napa has to be used
napa will directly install the dependencies in the node_modules directory
the postinstall script is equivalent to install. It is executed after the modules installation. However, I find it to be more explicit
you should place napa into the postinstall script
the paths provided in the browser field needs to be relative to the root package.json path. It is mandatory to start each entry by ./
it is possible to indicate files in another repository than node_modules when filling the browser field (e.g.: bower_components)
centralizing Browserify options in the package.json is a good practice since it allows to keep a constant behavior when invoking it in different ways (CLI, API)

Conclusion

Even though there is a little more code to write to setup a project, this solution provides a beautiful way to organize its code in logical bricks. It totally matches the way AngularJS has been thought.

Also, managing all the dependencies in a single place is really useful. Especially when developing full-stack JavaScript applications, hence potentially sharing dependencies between the frontend and the backend (e.g.: Async.js, Bluebird, Moment.js, highlight.js, …). Using a CommonJS loader allows to rely on the exact same versions of the modules both client-side and server-side.