We write event-driven applications, even if we don’t realise it at first, any application of decent size will tend towards being powered by events, it’s inevitable. Whether it’s a large-scale Redux architecture, React hooks like ‘useReducer’, NgRx in the Angular world, web sockets, custom-rolled systems etc, etc, etc. The list could go on forever.

Whilst an event based-architecture can lead to your programs having amazing properties in the form of ultra de-coupling & composition, it also comes with it’s own hidden cost — events by their nature are abstract and therefor we don’t typically get the best level of help from our IDE’s when it comes to creating, consuming & filtering streams of them.

So, What’s the problem?

To be productive in a large codebase that has any part of it powered by events, you need `type` information. There’s nothing more infuriating than listening for an event by using a string identifier, only to find out 3 hours later that there was a typo in the event name, or that an expected payload from an event didn’t match what you can actually see in your debugger! 😖

We need to start thinking of ways, especially in these dynamic languages, of mapping out every single event that our application can produce so that we
can handle them safely.

This is crucially important, you absolutely need to be able to verify that events are created correctly, with valid identifiers, and if they take one — a valid payload.

Prior Art, events as individual interfaces.

I’ve tried a number of different ways, and I’ve seen a million others, but the most common amongst them seems to be a variation on the following:

This approach lends itself nicely to being tucked away in its own file, a nice little ‘events.ts’ if you will. Now initially I agree it seems elegant at first, but since the types are written separate to the code that uses/consumes them, it requires a human to keep it up to date and make sure typos don’t exist.

Also, how would you use these when dealing with an event stream? For example, if you had a switch statement, how could you know inside each ‘case’ statement which payload you’re dealing with? With individual interfaces like this, the only option is to export a separate type that’s a union of all possible event shapes.

But now you’ve just created another thing to maintain! GRRR! and when it’s 20 events and you’re scrolling down the file to add your next event to this list, you might just be ready to throw your monitor out of the window. 📺

There’s also so much duplication — the fact that `SignIn` & `SignOut` are duplicated in some fashion across the interface naming scheme and the required ‘type’ field seems excessive — there has to be a better way?

But it gets worse, because these are just ‘types’, we need to either create functions for each to create a type-safe way of raising these events, or annotate objects at the point of emitting the event. The following shows the former, I’m omitting the latter for my own sanity.

This example is good in the type-safety sense. You have a guarantee on the function parameters, and since the function has a return-type annotation the type-checker will ensure the ‘payload’ here not only has the correct members but also that the parameters were valid to be used in that context (eg: a string where a string is expected)

But it’s far from good, we’ve also now duplicated the parameter names!

We have to remove some of this noise. Type-safety is nice, but this is coming at the cost of developer sanity! Also I believe examples like this are a prime reason that certain seasoned JS devs are so vocal about being anti-types — who can blame them?

A Step Forward, inferring the interface from the return type.

After looking at the code above, you’d be correct in thinking that you don’t even need the interface at all…

Thanks to conditional types being added to TypeScript back in 2.8, we now have useful helpers like ReturnType<T> which does exactly what it says on the tin — it infers the return type of a function if it can.

If you’re interested in type systems (you’re not?, how have you gotten this far?) then it’s worth a quick look at ReturnType<T>

It’s just a ternary operator, but for types, how neat! With a bit of practice you get good at being able to visually ‘parse’ this type of code :)

So, this is better than having a separate interface for the event + a function to create it. Now the type is driven by the implementation, not the other way around — this means you can change the function parameters & the return payload, and everywhere you’ve used that type will get the new type checking information.

A major downside though, is that you’d still need to maintain a list of them and union them together to get the full feature set of type safe events.

The keen-eyed amongst you may notice I’ve just used string literals in these screen shots and that the type-narrow may not actually work correctly — this is for simplicity & to prevent bringing in enums/consts in these examples that I’m actually encouraging you not to use. 😂

On the right track, getting Typescript to do more, with less.

So I’ve played around with numerous variations of the previous example in different sized applications, and overall it was OK. What’s pushed to me demand more though, is the work I’ve done in other languages like Rust & Elm.

It just hit me like a ton of bricks one day, the answer for a better way to type events in Typescript lies in it’s ability to model ADT’s (algebraic data types).

Let’s look at how you’d provide type information for the SignIn + SignOut events in Elm & how you’d create a union of them.

Seriously how cool is this? It’s just single identifiers SignIn & SignOut (they are type constructor in Elm) and some associated data — in the case of SignIn it’s 2 strings to represent the username and password (there are other, more descriptive ways, but this is not an Elm tutorial 😝).

In Rust it’s a similar story, there’s a little bit more syntax noise, but it’s ultimately the same thing.

It’s perfection. It’s just identifiers, and optional associated data. No more, no less. I needed to have this in TypeScript.

Challenge accepted

The goal is clear, a way to model event identifiers + optional payloads, with as small a footprint as possible. It should be like code-golfing, but with the goal being greater type-safety & developer productivity.

Looking at the rust implementation (since that has curly braces so it’s a fairer comparison 🤣) I wondered just how close I could get to it.

The first few attempts included using an actual JS object and having the ‘event creator’ function as the value to each identifier.

I was convinced for the longest time that this was a great approach. The idea would be that you’d define this object, and then call another function with it that would augment the return values to ensure they fulfilled the type + payload contract (so that they returned {type: …, payload:…} )

I put a considerable amount of effort into making this approach work with safety guarantees at all points, but I had another realisation when reviewing some of the large codebases I’ve worked on that were full of events — over 90% of the function I was using just forwarded on the params to the payload — they served no other purpose. In fact, in the few cases I found myself doing ‘work’ in those functions, it could easily be extracted out.

Moving to a types-only approach

Since Typescript supports object literal types, we can even closer to that beautiful world of Rust & Elm with the following:

If you squint, you’ll see we’ve reduced everything down to just the essentials — the identifier & the associated data. Now it did take me an embarrassingly long time to come to this solution, mainly because I was completely hindered by this notion that the events needed a ‘creation’ function.

Even though this does absolutely nothing yet, I knew this was an amazing idea.

Making it useable

Of course, that’s just a type definition right now, it’s not exactly ready to be deployed in a giant Redux Application now is it.

But just wait, with a few fancy Typescript feature and a single JS function, you’re about to witness the holy grail of working with events in Typescript.

#1 Switch to an enum for the identifiers

This is a no-brainer, and was only omitted from previous examples to reduce concepts — but since we want a single way to create and consume events, we’ll want to switch out the string keys for an enum — this is also a great way to name-space events.

Using string enums here is the perfect solution to our ‘identifier’ problem, since we can use the enum members as the discriminant (common property) but also it gives us the flexibility to implement pseudo namespaces in the sting values if we wish (or suffixes/prefixes etc).

There’s also an weirdly nice knock-on effect of this approach in that it will ensure the string values don’t collide (which can happen in enums), although only when the types on the ‘rhs’ differ, so it can’t be relied upon fully 😀

The whole point here though, is that throughout the application, we only ever would use the enum to reference this event —no extra functions or separate interfaces in sight.

#2 A way to create type-safe events

So we have the identifier & associated data part nailed, now we just need a single wrapper function so that we can apply some Typescript magic. We are going to essentially create a function that takes the enum member as the first param, and the associated data as the second. Beautifully simple.

Let’s look back at a Rust example for a second. This snippet will create the SignIn variant with it’s required data (I’ve skipped some rust-specifics here for brevity) Notice how the creation of this is almost identical to it’s definition.

Can we do this in Typescript? With full type safety? This is what I came up with…. 😂

Erm, now you’re thinking, where’s the beautiful or simple bits… Well, this is actually just taking a handful of the newer Typescript features in order to create this elm/rust clone. This code would be written once and then hidden away in a file that you never touch — the point is to enable the following:

The last 2 lines show how to create events in this system, the beauty comes from the fact that you don’t need to dream up function names for each event, but instead you just use the identifier and its data.

Msg here will only accept events from the User namespace (given as the first param, like a type constructor) and the second param would be type-safe based on that enum members value in the type object.

#3 benefits of Discriminated Unions/Algebraic data types

All of this type stuff is completely useless if you cannot also narrow the type of incoming events based on the common property. In our case we’re using enum members as the ‘type’ property so this should be simple enough — we want full type-safety in case blocks like this:

In this example we need to know that when a User.Token event is raised its payload is a string. Likewise we need to know when payloads are absent, or complex types etc etc.

This is where Typescript’s discriminated unions come into play — since we already have type safety at event creation, if we can nail getting type guards like this working, we’ll be onto something huge.

In the screenshot above, we wouldn’t get any type help. If you remember back to the type definitions for our events, we didn’t include the type or payload property — but also this reducer function doesn’t have a type annotation for the action — we’ll fix that now.

The above, whilst hard to read for those unfamiliar, is just known as a Mapped Type —this is a way fo creating a new type that is based on a transformation of the original type. In our case we had {identifier: value} , so this mapped type will do nothing more than create new types for each key

// before
{identifier: value}

// after 
{identifier: {type: identifier, payload: value }

Why do we do this? Because it allows us to create a union type of all possible enum + value combinations, so that when given to something like a switch statement the expected type narrowing occurs.

You’d add the following single line, where Messages here is just that object type that has the enum + associated value.

The square brackets give it away, you’re indexing into a type, but since keyof produces a union of all the keys, you get a union back. You are essentially indexing an object literal type with a union of its own keys. I know, it’s a bit of a mind bender, but it’s awesome.

The result is that Actions above now has exactly the correct type that enables the super-powerful type narrowing — if you hovered over it in our editor, the type would look like this:

And that’s pretty much it — if you can produce this type, you’re going to get awesome type safety throughout your application.

Conclusion

This has incredible type-safety, a nice api that matches languages with type constructors, has no duplication, uses a single identifier for event definition/creation/consumption and is basically just all-round better for all of your event-based needs.

If there’s any interest in a deep-dives into the more advanced typescript stuff, please request it and I may just write a post for type nerds like me :)

Check out the examples here https://codesandbox.io/embed/jpj18xoo85 — it should make things a lot clearer :)

— -

Like this? If you did, and you find yourself doing any front-end work, perhaps you’d enjoy some of my lessons on https://egghead.io/instructors/shane-osbourne— many are free and I cover Vanilla JS, Typescript, RxJS and more.

Finally, the TypeScript + Redux/Hooks/Events blog you were looking for. was originally published in HackerNoon.com on Medium, where people are continuing the conversation by highlighting and responding to this story.

Typescript is great, no complaints from me, but one thing that really caught my eye recently about Flow was this ability to alias & re-use the inferred type of a function’s return value.

That means, given a function that has it’s arguments annotated, and performs no side-effects, Flow will be able to work out the ‘shape’ or the ‘type’ of a return value, and allow you to use that elsewhere.

How to re-use the inferred return type of a function

I know it’s mouthful, but bear with me. Here’s a snippet I found whilst digging through about 2000 github issue threads. I’ve seen others, but this seems to work well, so…

type _ExtractReturn<B, F: (...args: any[]) => B> = B;
export type ExtractReturn<F> = _ExtractReturn<*, F>;

We’re exporting a generic type called ExtractReturn that accepts another type (in this case, the ‘typeof’ a function), and extracts the inferred return type — to use it with the function above, you’d use typeof setName like this:

import {setName} from './actions';
import {ExtractReturn} from './types';

type ReturnValue = ExtractReturn<typeof setName>

Don’t worry if you don’t understand exactly what’s going on here, just copy/paste the snippet and move onto the next bit — I’m being deliberately quite hand-wavey here as I want to focus on the point of this blog (and the fact I’m no type-system expert myself)! But anyway, onto the good stuff!

How this can help in a Redux Project

The most common approach I’ve seen to providing type-safety in a Redux Application is to have the shape of each action defined separately from your actual function implementations. So you’d typically define all of the action objects your application is ‘allowed’ to use, and then you’d re-use those types in action-creators and reducers. It normally looks something like this:

Before:

export const SET_NAME = 'SET_NAME';
export const SET_AGE = 'SET_AGE';

export type SetName = {type: 'SET_NAME', payload: string}
export type SetAge = {type: 'SET_AGE', payload: number}

const setName = (name: string): SetName => {
    return {type: SET_NAME, payload: name}
}

const setAge = (age: number): SetAge => {
    return {type: SET_NAME, payload: age}
}

export type Actions = SetName | SetAge;

Of course this example is tiny with just 2 actions creators and I’ve condensed it down onto 1 imaginary file for the sake of space, but it’s enough to explain the concepts here.

Defining each action ‘shape’ as it’s own type as seen on lines 3 and 4, means that you can be very specific about an object/action that a function should return. Given that you’ve had to declare them all up front like this, it gives very strong guarantees that you’re not going to be dispatching unexpected object shapes into your Redux store. Awesome.

Crucially though, this technique also allows you to create what’s known as a ‘tagged union’ as seen on the last line. It’s known as a ‘discriminated union’ in Typescript land, and is basically a way of a narrowing any type-checking based on the value of a particular field — in our case it’s the ‘type’ field from the object.

So with this technique of defining all actions as separate types, we can both enforce the return-types of action-creators whilst also narrowing our type-checking in reducers based on which action was fired. All sounds great, right?

It is great actually — I’ve used this technique before without any real issues, but I still find it interesting to experiment with these type systems in an attempt to extract as much value from them with as little typing as possible.

So looking back at the previous code, my personal opinion is that having to come up with new names for each and every Action, duplicating the action name, and having to annotate the return value of every action-creator are all things that can be avoided.

So with that in mind, if we just make use of the ExtractReturn helper from before, the previous example could be be reduced to the following:

After:

export const SET_NAME = 'SET_NAME';
export const SET_AGE = 'SET_AGE';

const setName = (name: string) => {
    return {type: SET_NAME, payload: name}
}

const setAge = (age: number) => {
    return {type: SET_AGE, payload: age}
}

export type Actions =
    ExtractReturn<typeof setName> |
    ExtractReturn<typeof setAge>

The fact that we’ve reduced the duplication of the action names themselves is great, but we’ve also removed the need to come up with separate names for our actions — we all know just how hard naming things are, right?!

The exported type Actions on the last line will also still generate the ‘tagged union’ as described previously, meaning we’re not losing out on any of the (awesome) narrowed type-checking that we were getting before — yay!

Perhaps most interestingly though, is that we’ve now inverted the source-of-truth to be our actual code, rather than the separate types. This means any changes to the return values in any action-creators are automatically propagated throughout the system — there’s no need to update any separate types!

This is a trade-off that some people will not be comfortable with, and I would totally understand that — I can see the benefit of having all action object types explicitly defined separately from the code (as I said, I’ve used this approach before without issue).

But, having worked on large typed projects (both in Typescript & Flow) I’ve ended up with a few opinions about this type of stuff:

• Types are extremely important, and the larger the project, the larger the importance & also the larger the payoff.
• If you’re going to use a type-checker, go all in. It doesn’t work nearly as well as you might imagine having only a subset of a project typed.
• Type annotations are noisy though, and ‘noise’ in code is always something we should aim to reduce.
• If you can use the type-checker to actually create types for you dynamically based on your code, do it! This blog is an example of that and I hope we see much more of this.

One final note

When I use phrases such as ‘less typing’ and ‘fewer key strokes’ I’m NOT talking about creating ‘shorter’ code in terms of actual characters — I’m talking directly about having less *things* to create, import, export, name & maintain. This blog post has shown a way of producing very similar type-safety with dramatically less code (when you consider a real code-base).

Hope you enjoyed this experiment!

Links:

• Gist — https://gist.github.com/anonymous/9ffb548a38b6c24114d4bad360bfe8f8
• Flow Try

Like this? If you did then perhaps you’d enjoy some of my lessons on https://egghead.io/instructors/shane-osbourne— many are free and I cover Vanilla JS, Typescript (soon Flow?), RxJS and more.

Redux & Flow-type — getting the maximum benefit from the fewest key strokes was originally published in HackerNoon.com on Medium, where people are continuing the conversation by highlighting and responding to this story.

Have you ever been part of a project that required some kind of ‘build’ or ‘compilation’ step? Perhaps a project where you manually edit your ‘source files’ first, then you run some command to produce the final ‘production-ready’ assets?

Just want to see the code?, you can skip straight to the repo I setup for this post

Terminology: Every time you see the work ‘artifact’ in this post, I’m referring to something like an executable, directory or anything else that is produced as part of your workflow — it’s typically the thing you want to run on a server & it’s almost always excluded from version-control.

Build tools have extremely different requirements to those of your production App.

This is a big problem. Whether it’s a simple blog generated from Markdown files, a fully-fledged SPA written in something like Angular or React, or any other type of project that uses tooling — the dependencies required to ‘build’ your project — that is, take your source files and produce the actual thing you want to throw on a server — are vastly different.

Just take a look inside your `node_modules` directory (or equivalent in your chosen lang/env) — I bet all (or most) of those packages will only be required for the build process — and if that’s true, they have no place on a production server, ever!

Current solutions.

Of course, no-one right now would admit to building their projects on the same server that runs their App, but we all know it happens… too often.

To get around this problem, the more responsible projects out there will tend to do one of the following:

• 1) Have developers run the ‘build’ command locally, producing an artifact that is then ‘uploaded’ somewhere, or added to a docker image etc…
• 2) Have a separate CI service sitting in between Github & the production server — the artifact can be produced there instead and then deployed to a server…
• 3) Run the build process on the same server as that which will run the app in production…

But now, for those using Docker, there’s a better way. A technique that allows you to consolidate your build + production setup to a single Dockerfile. This has huge implications for the future as it allows things such as auto-builds/deployments often without the need for yet another 3rd party service

Docker multi-stage builds

No need for jargon here, the concept is so simple it’s brilliant.

• 1) Create the environment needed for your build process
• 2) Run that build process to produce your artifact
• 3) Create your production environment
• 4) Copy the artifact into your production environment
• 5) Discard EVERYTHING ELSE from the build environment.
• 6) profit?…

The fact that Docker handles all of this complexity is amazing — now let’s run through a real-world example to fully understand it.

I’m going to use the popular create-react-app CLI tool in this example, but you can take the concept and apply it to any similar situation.

Tutorial using 'create-react-app'

Step 1: Install create-react-app

yarn global add create-react-app

Step 2: Create a new project

create-react-app docker-build

Notes:

• After creating a new project, you’ll notice you have a ‘src’ directory containing the files you should edit in development.

Step 4: Add build process to Dockerfile

We’ll build upon the latest official NodeJS Docker image, which comes with yarn pre-installed.

FROM node:7.10 as build-deps
WORKDIR /usr/src/app
COPY package.json yarn.lock ./
RUN yarn
COPY . ./
RUN yarn build

Notes:

• On line 1, we’re using the FROM <image:tag> as <name> format which is new to Docker 17.05.
• The as build-deps part allows us to name this part of the build process. That name can then be referred to when configuring the production environment later.
• On lines 4 & 5 we copy package.json and yarn.lock into the image and then run yarn — this separates the dependency installation from the edits to our actual source files. This allows Docker to cache these steps so that subsequent builds — one’s in which we only edit source files and don’t install any new dependencies — will be faster.
• Next on lines 6 & 7 we copy everything else into the image and then run the build command. This will produce the ‘artifact’ inside of the build directory — just as it would if you were to run this command locally!
• Be careful, copy . ./ can be quite dangerous is it will copy the entire current directory into a build context, which may be huge! Add a .dockerignore file to combat this, mine would look something like https://gist.github.com/anonymous/f1b3e2cc530900338a0c38bce5e0e4c1

Step 5: Add production environment to the SAME Dockerfile

This is where things start to get seriously interesting! In the exact same Dockerfile we can add the setup for our production environment, right below the setup for the build process!

When Docker sees a second FROM statement, it will begin an entirely new ‘build stage’ — which includes NOTHING from the first step. That’s right, the whole thing is discarded… kind of. Crucially it does allow you access to the previous builds file system. So, this is where everything starts to come together and make sense, because Docker allows you to selectively copy anything you like from the first build step, into the second one!

This means we can grab hold of the build directory, which is our ‘artifact’ and discard everything else from the first step. So everything about the base NodeJS Docker image is discarded, along with all the files we don’t choose to copy over into the new build step.

In this example, with create-react-app , that means we get to wave goodbye to the 22,676 files required to build the project — none of those are needed to serve the application, so we don’t want them lingering around!

Let’s see it in action

FROM nginx:1.12-alpine
COPY --from=build-deps /usr/src/app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Notes:

• We’re using one of the official nginx images here to serve our application, but this could be any other type of server — I only chose nginx as it’s popular & I know how to configure it :)
• On line 2 is the shiny new stuff. The COPY statement has been around since Docker first hit the scenes, but so far it’s been limited to copying files from a context (like a host) into an image. The new part is the flag --from=build-deps — if you remember back to the first stage, build-deps is the name we gave that stage, and this is how we can refer to it here.
• Again on line 2, we know that create-react-app creates a build directory as an artifact, so we add that path to the working directory and end up with: /usr/src/app/build this is the absolute path of our artifact inside the first stage.
• So, we know how to access the artifact from the first stage, now we just need to copy it into the correct place in our production environment — and because we’re using stock nginx, that directory is /usr/share/nginx/html
• The final 2 lines are just the regular docker commands to expose a port and run the server when a container start.

Step 6: Build the image!

Now we get to put it all together — we have both our development build process & production environment specified in a single Dockerfile — it should look something like:

Now we can instruct Docker to create an image from this:

docker build . -t shakyshane/cra-docker

Notes:

• docker build . instructs Docker to use the current directory as it’s build context
• -t shakyshane/cra-docker instructs Docker to ‘tag’ this particular build. In this case I’m naming the image as it would appear on my Docker Hub account, but you can use any tag name you want.

Step 7: Run it locally to test it works!

After running the previous build command, you can now use the tag name to start a container from this image.

docker run -p 8080:80 shakyshane/cra-docker

Notes:

• -p 8080:80 allows us to map the port 8080 on our local dev machine to port 80 inside the container — you can omit the first part if you’re happy for Docker to assign a random port for you, eg: -p 80 will result in something like http://localhost:32888 — which will change each time you run it.
• If it all worked well you should now be able to see the following in your browser:

Next steps

Now that you’ve seen how to build and serve your project with Docker, you can go ahead and take advantage of everything that containers have to offer, some examples are:

• 100% consistent builds across any machine that can run Docker
• Fully automated deployments via a service like Docker Cloud (check this example which includes fully-automated SSL certs)
• Run your EXACT production setup locally before deploying
• Combine with other services, eg: for a frontend App you might want to add something like a CouchDB instance — this is a trivial task with Docker.
• etc etc

Docker is taking over the world, and with every release it’s getting easier for regular devs to utilise its power!

Final Notes:

The example given here does not include the production-ready configuration for the nginx server — I didn’t want the details of such a thing to cloud the content of this post — if there’s demand I can follow up with a post detailing that!

Links:

Use multi-stage builds

Like this? If you did, and you find yourself doing any front-end work, perhaps you’d enjoy some of my lessons on https://egghead.io/instructors/shane-osbourne— many are free and I cover Vanilla JS, Typescript, RxJS and more.

JavaScript Framework Battle: ‘Hello World’ in each CLI

I was just wondering, given that most of the big JavaScript frameworks offer a Command-line interface (CLI) tool nowadays — to automate the creation of new projects and the building of production assets — how do they actually compare to each other? I mean surely they must all be hitting the same ‘ballpark’ when it comes to bundle size/render perf right? Maybe it’s not as close as you might think.

I decided to test this out by installing 6 popular CLI tools — Create React App, Angular CLI, Ember CLI (for both Ember & Glimmer), Vue CLI, Create Inferno App and Create *Preact App globally onto my laptop, and then follow the official documentation for each.

I was only interested in the ‘out of the box’ project generation — so there was literally zero application code added by me. I just ran the relevant command to scaffold a project, then I immediately ran the production build…

I think this is an interesting test, because although each framework can give you more or less features by default, the point here is that the authors of the framework must deem this default scaffold+build process to be ‘the best you’re going to get’ out of the tool, and that’s what I found fascinating in the results.

So let’s start in this first post by looking at just two easy metrics, JavaScript bundle size & JS first render time.

Note: see https://github.com/shakyShane/arewereadyformobileyet for the automated results.

JavaScript Bundle Size

For each CLI, I ran the ‘as-documented’ command for producing a production-ready build. T̶h̶e̶n̶ ̶I̶ ̶m̶a̶n̶u̶a̶l̶l̶y̶ ̶g̶z̶i̶p̶p̶e̶d̶ ̶t̶h̶e̶ ̶o̶u̶t̶p̶u̶t̶ ̶(̶u̶s̶i̶n̶g̶ ̶d̶e̶f̶a̶u̶l̶t̶ ̶m̶a̶c̶O̶S̶ ̶g̶z̶i̶p̶ ̶c̶o̶m̶p̶r̶e̶s̶s̶i̶o̶n̶ ̶s̶e̶t̶t̶i̶n̶g̶s̶)̶ ̶t̶o̶ ̶g̶e̶t̶ ̶t̶h̶e̶s̶e̶ ̶r̶e̶s̶u̶l̶t̶s̶.̶

Then, I spin up a lightweight server pointing at the resulting ‘build’ or ‘dist’ directory with Gzip enabled. Finally I pump the URL from this server into Lighthouse & measure the size of all the Javascript combined.

Notes

• Preact (and other micro libs, didn’t want to clutter the chart) obviously come out on top given they are simply a thin layer on top of the DOM. You’ll naturally get more features out of something like Angular & Ember, given they are full frameworks — but I’ve left a micro lib in here because with PWAs becoming so popular/necessary, it’s often the case that Apps are built by composing many of these micro libs together and given the starting point is 8kb, you’d need to add a LOT of them before your code is anywhere near the size of what Ember/Angular are shipping by default.
• Interesting how close React & Vue are nowadays — although I believe Vue can be trimmed further depending on which options you select in the CLI scaffold stage (I just went with whatever was presented as a ‘default’)
• Angular seems to have shed about 50kb since I last tried a few months ago, so they are certainly making progress;
• Ember is off the chart (size-wise) and cannot be considered suitable for mobile at this point (to be fair, I don’t think they claim to be).
• Glimmer (by the Ember team) is the newest, and coming in at 34kb is impressive to say the least. Great work.

First JavaScript Render

Next, I throttled the connection speed in the network panel Chrome Dev Tools (down to regular 3G) and applied the 5x CPU slowdown in the timeline section. Then I hit ‘reload’ with screenshots enabled and then scrubbed through until I spotted something appear on screen that was the result of the framework running.

There are of course many other ways of measuring this more accurately — depending on what type of answer you want. Not to mention the difference that may be made via SSR etc, but still, it’s pretty obvious that more JS === more time. Even if a page were rendered by the server and picked up on the client side by the JS framework — the render times in that chart above would simply become the ‘time to interactive’ as the JS still needs to download/be-parsed/be-executed, whether there’s static HTML there or not. A user ‘seeing something’ on the screen is simply not enough if the core product includes JS interactivity.

Interactive in 2 seconds…

I’ve often heard the mythical goal is ‘interactive in 2s’ (with the 3G throttle and CPU slowdown) and recently at my day-job I set a target on a very large project of having the initial bundle (enough JS for rendering, interactivity and Ajax) to be less than 50kb. Safe to say that hitting this target required me to chose a micro view lib like Preact, which, because of its tiny size, allowed me ‘space’ to bring in a few essential libraries whilst still keeping things below 50kb.

How I came up with the results

Create React App

Commands:

• Install: yarn global add create-react-app
• Scaffold: create-react-app cra-test
• Production Build: yarn run build
• JS Bundle Size: 46kb
• First render: 770ms

Angular 2 CLI

Note: Why is aot not automatically part of the target=production configuration? It’s extremely easy to miss and I only knew about it because of a Podcast addiction :p

Commands:

• Install: yarn global add @angular/cli
• Scaffold: ng new ng-test
• Production Build: ng build --aot --target=production
• JS Bundle Size: 92kb (4 files)
• First render: 1500ms

Ember CLI (Ember app)

Note: The Ember scaffold process does NOT render any JS by default, which leads to a false ‘first render’ score — so I followed the instructions and added an outlet as directed. This is the only CLI tool I had to do this for.

Commands:

• Install:
• - yarn global add ember-cli
• - yarn global add bower
• Scaffold: ember new ember-test
• Production Build: ember build --target=production
• JS Bundle Size: 198.4kb (4 files)
• First render: 4200ms

Ember CLI (Glimmer app)

Note: There also appears to a --suppress-sizes flag, but when I used that, the JS bundle it produces appeared to be the same size + caused an error in the browser

Commands:

• Install: yarn global add ember-cli/ember-cli
• Scaffold: ember new glimmer-app -b @glimmer/blueprint
• Production Build: ember build --target=production
• JS Bundle Size: 34kb
• First render: 1000ms

Vue CLI

Note: Vue was by far the most confusing CLI experience — the need to specify a template + lots of questions about tooling — it feels very off-putting to newcomers, where’s the ‘default’?

Commands:

• Install: yarn global add vue-cli
• Scaffold: vue init webpack vue-cli (followed by lots of questions)
• Production Build: npm run build
• JS Bundle Size: 43.48kb (4 files)
• First render: 840ms

Create *Preact App

Note: I’m not entirely sure this is well supported, but it’s the first/only CLI tool I could find for a ‘micro’ lib.

Commands:

• Install: yarn global add create-preact-app
• Scaffold: create-preact-app preact-test
• Production Build: npm run build
• JS Bundle Size: 8.8kb
• First render: 412ms

Create Inferno App

Commands:

• Install: yarn global add create-inferno-app
• Scaffold: create-inferno-app inferno-test
• Production Build: yarn run build
• JS Bundle Size: 70kb
• First render: 737ms

Did you enjoy this? Perhaps you’d enjoy some of my lessons on https://egghead.io/instructors/shane-osbourne — many are free and I cover Vanilla JS, Typescript, RxJS and more.

JavaScript Framework Battle: ‘Hello World’ in each Command-line interface was originally published in DailyJS on Medium, where people are continuing the conversation by highlighting and responding to this story.

The goal of this second post is highlight the differences in workflow between the development environment that we use to build our apps and the production environment in which our apps actually run.

What’s different in production?

This post will only cover a single-server setup. We’ll do it all the manual way so you can see all the bits and pieces that are needed.

Source files:

In development, we usually mount the current working directory into a container so that changes can be made to the source code and will be immediately reflected in the running application. In production however we’ll copy our source files directly into images so that they can be run independent of the host (ie: on a server somewhere).

Exposed ports:

In development we’ll sometimes bind ports on the host to containers to enable easier debugging. This is not required in production as services can communicate through the network docker-compose creates automatically for us.

Data persistence:

In development we setup MySql with a named volume to allow the data written to it to persist (even when our containers stop and restart) — but we didn’t handle situations where the app may want to write to disk (in the case of Laravel, this happens with views) — so, in production we’ll need to create a volume which will allow the data that’s written to disk to persist.

Environment Variables

In development we just had a .env file that was available to the container along with all the rest of our source code. In production we’ll load a different one in dynamically

SSL & Nginx config

We’ll need to configure our web server to enable secure connections, but we’ll want to load the path to the certs dynamically at run time so that we can swap live ones for self-signed when testing the production setup locally.

Step 1 — Prepare the ‘app’ image

In the first post we created a PHP-FPM based image that was suitable for running a Laravel application. Then all we needed to do was mount our current directory into that container and the app worked. For production we need to think about it differently though, the steps are:

1. Use a Laravel-ready PHP image as a base
2. Copy our source files into the image (not including the vendor directory)
3. Download & Install composer
4. Use composer within the image to install our dependencies
5. Change the owner of certain directories that the application needs to write to
6. Run PHP artisan optimize to create the class map needed by the framework.

So let’s dive in. First up you’ll want to create the app.dockerfile that we’ll use to accomplish all of this.

Notes:

• On line 1 we’re building from an image I’ve published to the Docker hub that contains just enough to run a Laravel Application.
• Because on line 3 & 5 we use the COPY command, Docker will check the contents of the what’s copied each time we attempt a build. If nothing has changed, it can use a cached version of that layer — but if something does change, even a single byte in any file, the entire cache is discarded and all following commands will execute again. In our case that means every time we attempt to build this image, if our decencies have not changed (because the compose.lock file is identical) then Docker will not execute the RUN command that contains composer install and our builds will be nice and fast!

Step 2 — create .dockerignore

In the previous snippet we saw the line COPY . /var/www This alone would include every single file (including hidden directories like .git) resulting in a HUGE image. To combat this we can include a .dockerignore file in the project root.

It works just like the .gitignore you’re used to, and should include the following as a minimum.

.git
.idea
.env
node_modules
vendor
storage/framework/cache/**
storage/framework/sessions/**
storage/framework/views/**

Notes:

• The last three lines are there to ensure any files written to disk by Laravel in development are not included, but we do need the directory structures to remain.

Step 3 — Build the ‘app’ image

With the files app.dockerfile and .dockerignore created, we can go ahead and build our custom image.

docker build -t shakyshane/laravel-app .

Notes:

• This may take a few minutes whilst the dependencies are downloaded by composer.
• -t here instructs Docker to ‘tag’ this image. You can use whatever naming convention you like, but you need to consider where this image is going to end up when deciding. In this example I’m publishing this image under my username on docker hub (shakyshane) and want the repo to be named laravel-app You can see what I mean here https://hub.docker.com/r/shakyshane/laravel-app/ & for the more visual amongst us:

When the image has built successfully, you can run docker images to verify the image is tagged correctly.

Step 4— Add the ‘app’ service to docker-compose.prod.yml

Now we can begin to build up the file docker-compose.prod.yml starting with our app service. (as in the first post, these are all under the ‘services’ key, but don’t worry as there will be full snippets later).

#  The Application
app:
  image: shakyshane/laravel-app
  volumes:
    - /var/www/storage
  env_file: '.env.prod'
  environment:
    - "DB_HOST=database"
    - "REDIS_HOST=cache"

Notes:

• We use image: shakyshane/laravel-app here to point to the image we just built in the last step. Remember this has all of our source code inside it, so we do not need to mount any directories from our host.
• We need a way for files written to disk by the application to persist in the environment in which it runs. Using a volume definition in this manner /var/www/storage will cause Docker to create a persistent volume on the host that will survive any container stop/starts.
• We’re going to set up Redis as the session and cache driver, but I’ve yet to find a way to stop Laravel writing view caching to disk, that’s why this single volume is required.
• We use env_file: ‘.env.prod’ to mount a Laravel environment file into the container. This part is something that can be improved by using a dedicated secret-handling solution, but I’m not dev-opsy enough to do that, and in cases where we’re just using a single-server setup, I think this approach is ok. (please, any security experts out there, correct/point me in the right direction)

Step 5 — Prepare the ‘web’ image

So, now that we’re building a custom image that contains a PHP environment, all of our source code and all application dependencies, it’s time to do the same for the web server.

This one is much simpler. We’re just going to build Nginx, copy a vhost.conf into place (suitable for a Laravel app), and then copy in the entire public directory. This will allow nginx to serve our static files that do not require processing by the application (such as images, css, js etc)

So go ahead now and create web.dockerfile . It only needs the following:

FROM nginx:1.10-alpine

ADD vhost.conf /etc/nginx/conf.d/default.conf

COPY public /var/www/public

Notes:

• This time we’re using nginx:1.10-alpine — the -alpine bit on the end means this base image was built from a teeny tiny linux base image that will shave 100s of MB from our final image size.
• The alpine build also supports HTTP2 out of the box also, so, bonus.

Step 6 — Create the NGINX config

Save the following as vhost.conf — that’s the name we had above in web.dockerfile

Notes:

• Where you see paths like/etc/letsencrypt/live/example.com in that file above, you can change example.com for your own domain if you have one, but either way, go and download some self-signed certs from http://www.selfsignedcertificate.com/ (or generate your own if you know how) and stick them in the following directory certs/live/example.com — it should look like this when done.

• The idea is that when testing locally, you can pass in something like LE_DIR=certs — referring to your local directory, but then on the server you can pass LE_DIR=/etc/letsencrypt — which is where the certbot will dump your certs. This will create security warnings locally due the self-signed certificates, but you can click past the warning to fully test HTTP2 + all your links over a HTTPs connection.

Step 7 — Build the ‘web’ image

With the files web.dockerfile and vhost.conf created, we can go ahead and build our second custom image.

docker build -t shakyshane/laravel-web .

Notes:

• Just as the previous image, we tag this one to match the repo name under which it will live later.

Step 8— Add the ‘web’ service to docker-compose.prod.yml

# The Web Server
web:
  image: shakyshane/laravel-web
  volumes:
    - "${LE_DIR}:/etc/letsencrypt"
  ports:
    - 80:80
    - 443:443

Notes:

• We mount the directory containing our certificates using an environment variable. Docker-compose will replace ${LE_DIR} with the value we provide at run time which will allow us to swap between live/local certs.
• We bind both port 80 & 443 from host->container. This is so that we can handle both insecure and secure traffic — you can see this in the second server block in the vhost.conf file above.

Step 9 — Add MySql and Redis services to docker-compose.prod.yml

Finally, the configuration for MySql and Redis needs to be placed in our docker-compose.prod.yml file — but for these we do not need to build any custom images.

version: '2'
services:

  # The Database
  database:
    image: mysql:5.6
    volumes:
      - dbdata:/var/lib/mysql
    environment:
      - "MYSQL_DATABASE=homestead"
      - "MYSQL_USER=homestead"
      - "MYSQL_PASSWORD=secret"
      - "MYSQL_ROOT_PASSWORD=secret"
  
  # redis
  cache:
    image: redis:3.0-alpine

volumes:
  dbdata:

Notes:

• We use a named volume for MySql to ensure data will persist on the host, but for Redis we don’t need to do this as the image is configured to handle this for us.

Step 10 — Create .env.prod

As with any Laravel Application, you’re going to need a file containing your app’s secrets, a file that is usually different for each environment. Now because we want to run this application in ‘production’ mode on our local machine, we can just copy/paste the default Laravel .env.example sample file and rename to .env.prod — then when this application ends up on a server somewhere we can create the correct environment file and use that instead.

Step 11 — Test in production mode, on your machine!

This is where things start to get seriously cool. We’ve built our source & dependencies directly into images in a way that allows them to run on any host that has Docker installed, but the best bit is that this includes your local development machine!. Say goodbye to test locally, pushing and hoping for the best!

At this point we just have a final command to run, but it’s worth recapping what you should’ve done up to this point.

1. Created a app.dockerfile , built an image from it & configured it in docker.compose.prod.yml
2. ^ same again for web.dockerfile
3. Created a .dockerignore file for exclude files and directories from COPY commands
4. Created the vhost.conf file with NGINX configuration, created self-signed certs for local testing & added the docker-compose.prod.yml config for it
5. Added the Redis & MySql configurations
6. Created a env.prod configuration file

Your docker-compose.prod.yml should look something like the following:

version: '2'
services:

  #  The Application
  app:
    image: shakyshane/laravel-app
    working_dir: /var/www
    volumes:
      - /var/www/storage
    env_file: '.env'
    environment:
      - "DB_HOST=database"
      - "REDIS_HOST=cache"

  # The Web Server
  web:
    image: shakyshane/laravel-web
    volumes:
      - "${LE_DIR}:/etc/letsencrypt"
    ports:
      - 80:80
      - 443:443

  # The Database
  database:
    image: mysql:5.6
    volumes:
      - dbdata:/var/lib/mysql
    environment:
      - "MYSQL_DATABASE=homestead"
      - "MYSQL_USER=homestead"
      - "MYSQL_PASSWORD=secret"
      - "MYSQL_ROOT_PASSWORD=secret"

  # redis
  cache:
    image: redis:3.0-alpine

volumes:
  dbdata:

Once that’s in place, all that’s left to do is run a single command…

LE_DIR=./certs docker-compose -f docker-compose.prod.yml up

And in a few moments your application will be accessible at https://0.0.0.0

Congratulations, you’re now running your application in a way which is 100% reproducible on a production server — no kidding! Once the 2 images we built are published to a registry like Docker Hub, all you’d need to do is place the docker-compose.prod.yml & an .env file on a server and your application will be running using the exact system you already tested on your local machine.

This is developer bliss.

Next Steps.

I can only cover so much here, and the main focus of this blog was to fill in the pieces I found to be lacking from other posts in terms of the differences between using Docker in Development and then in Production.

As I mentioned at the beginning, this setup has served me well in a single-server environment where I did the following steps to get it running in production:

1. Created a Digital Ocean Droplet with Docker pre-installed.
2. Followed one of their guides for installing docker-compose (it doesn’t come pre-installed on Linux like it does on Docker for Mac/Windows)
3. Setup auto-building in Docker Hub, so that when I push to Github the two images are automatically built.
4. Used certbot to generate SSL certs on the server
5. Ran the same docker-compose command seen above, but this time swapping the LE_DIR part for the path on the server to the certs. eg: LE_DIR=/etc/letsencrypt docker-compose -f docker-compose.prod.yml up

There’s so much more to Docker however, I’m just showing you the first steps here so you can grasp some concepts about what it means to containerize your application.

Here’s the REPO, you can find all the files in there, have fun!

Next things to look at:

• CI: Lots of the steps in this post can be automated, for example, you may use a CI service to build and publish your images to a registry, along with running tests etc. I would recommend that you get familiar with building/pushing images manually first however, just so that you fully understand the workflow bits and pieces before you move into a completely automated flow.
• Secret & certs management: Having an entire application along with it’s running environment neatly packaged into containers just feels like the correct thing to do, but due to my lack of dev opts/sysadmin skills, I honestly don’t know how to remove these 2 items from being mounted at run time. I hear that Docker is currently working on it’s own solution for secrets management, which will be so cool to have it integrated. Container services such as Kubernetes already provide solutions for it out of the box however, and then there’s also dedicated things such as Vault…. So much to learn… :)
• Swarm mode, scaling etc: Docker has native support for scaling applications across multiple host using simple CLI commands. Very much looking forward to using this in the future. I’ve tried using docker-machine to boot up cloud servers on Digital Ocean and I can tell you right now that it’s a mind-blowing experience — especially when you realise that all of your regular docker commands, including things such as docker-compose, all work over the network… Crazy cool.

Like this? If you did, and you find yourself doing any front-end work, perhaps you’d enjoy some of my lessons on https://egghead.io/instructors/shane-osbourne— many are free and I cover Vanilla JS, Typescript, RxJS and more.

The goal in this first post is to create a reproducible development environment that is lightweight, fast & does not depend on anything being globally installed on our local machine (other than docker itself).

So, we’re talking about achieving the following goals.

• No Mamp or similar programs
• No Vagrant or similar VM setups
• No Globally installed PHP
• No Globally installed Composer

Step 1 — grab the latest Laravel release

I’m using curl here to grab the latest release from Github, but feel free to obtain a copy of the source however you like — you could just do a git clone — but if you do, don’t forget to wipe the .git directory immediately after.

We’re not following the official guide for setting up Laravel here as we don’t want the hassle of installing PHP/Composer globally on our dev machine

curl -L https://github.com/laravel/laravel/archive/v5.3.16.tar.gz | tar xz

That would create a directory called laravel-5.3.16 — you should rename it to whatever you want your project to be. eg mv laravel-5.3.16 my-site and then cd into it.

Step 2 — Install dependencies

We need to run composer install to pull in all of the libraries that make up Laravel — we can use the composer/composer image from the docker hub to handle this for us.

We’ll create a throw-away container by executing the following command.

docker run --rm -v $(pwd):/app composer/composer install

Notes:

• We use the--rm flag to ensure this container does not linger around following the install.
• -v $(pwd):/app is used to mount the current directory on the host (your cpu) to /app in the container — this is where composer running inside the container expects to find a composer.json
• -v $(pwd):/app will also ensure that the vendor folder created by composer inside the container is also visible on our machine.

Step 3 — create the development docker-compose.yml file

We’ll be using 2 separate files to define how our environments should run. 1 for development, and another for production. Now, Docker-compose does actually support using multiple input files, allowing you to override specific keys — but because of the way it merges arrays, it will not be suitable for our particular use case. We’ll just have to put up with a bit of duplication in both files.

Anyway, you’ll need to create the following file:

• docker-compose.yml

It should begin with…

version: '2'
services:
   ... our services will go here

… into which we can begin to add our services.

PHP-FPM

This will handle executing the code within the application. We’ll also use this service to execute arbitrary php scripts — such as running artisan the CLI tool that ships with Laravel. (remember this block is under the ‘services’ key from above — don’t worry, there’ll be full snippets later)

Notes:

• We’re going to use a separate app.dockerfile (line 4) to build our image as we want to control exactly what modules PHP is using.
• We set the working directory to /var/www — that’s where the app code will be inside the container, so it’ll save us having to CD into that folder should we ever attach to the container. It will also make exec commands shorter (we’ll see an example of this shortly)
• We use a single volume definition ./:/var/www to mount the everything in the current directory on the host into /var/www in the container. This will allow us to make changes to our source code and have them reflected in the running application immediately. This is going to make your app feel sluggish in the browser — a few hundred ms lag (especially on OSX), but fear not — in part 2 when we transition to a production setup the speed issues will no longer be there.

• The environment variables DB_PORT & DB_HOST are set here to match up with the database container we’ll create shortly

Now we need to create the app.dockerfile that we referenced in the build setting above.

Notes:

• php:7.0.4-fpm is used here, but could be anything of your choosing.
• The rest is the just basics needed for a typical Laravel CRUD app, with imagick thrown in for good measure (I have a few photo apps :))

NGINX

Next, we need a web-server configured to handle both the serving of static files, and pass-through of requests that need to be handled by the Laravel application. We’ll follow the same pattern as before, this time naming the service web and it’s accompanying file web.dockerfile

Notes:

• We use volumes_from here to re-use what we defined in the PHP-FPM service above. This means that this nginx container will inherit the /var/www directory (which is in turn mounted to our development machine)
• we map port 8080 on the host to 80 in the container. This is so that we can access 0.0.0.0:8080 whilst in development and won’t need to mess around with host names.

Next, we’ll create the web.dockerfile mentioned above:

Notes:

• As you can see, it’s just the standard nginx official image, with the vhost.conf file from our local directory (created next) added to configure the server.

And here’s that file vhost.conf

Notes:

• Notice how on line 12 we hand off php requests to app:9000 — this works because docker-compose will automatically link our services in a way that allows them to talk to each other via these simple hostnames.
• The rest is just very basic nginx config — it’s not tuned in any way for performance or security— we’ll handle those in another post!

MYSQL

Next, we’ll configure the database, but we need to handle this one slightly differently to the previous services. With PHP-FPM & Nginx, we want files from our local directory to be accessible inside containers, to help speed up the development process. But this is not the case with a database — instead we want files created in the container to persist, allowing us to stop & restart services without losing data. This can also be achieved with a volume, only this time there’s no need for it to be synchronised with our host files.

Notes:

• On line 16 we create a named volume, dbdata (the trailing : is deliberate, a limitation of yaml that you don’t need to worry about)
• Then, on line 7 we reference that volume by using the format <name>:<dir> So this is saying “mount the directory /var/lib/mysql from the volume named dbdata”
• We set the required environment variables on lines 9, 10, 11 & 12 as required by the MySql docker image.
• We used homestead as the database/user name & secret as the password as these values match what can be found in the default .env that ships with Laravel, meaning we won’t have to change it there.
• Finally on line 13 we create an addition port mapping of 33061 on the host to the regular 3306 inside the container. This is done solely to allow external tools easier access to the database whilst in development — it will not be needed in the production setup.

All services together

Let’s look at the final docker-compose.yml now to see how these pieces fit together.

Starting the services

If you’re following along, we’re almost there! But before we boot up the environment, we need to ensure 1) you ran composer install as instructed earlier in the post & 2) you have created the following files in the root of the project (all detailed above).

• docker-compose.yml
• app.dockerfile
• web.dockerfile
• vhost.conf

Here’s a gist showing all the files together, for your reference/copy&paste needs.

Once you have all of those in place, you can go ahead and execute the following command which will start all 3 services.

docker-compose up

Notes:

• The very first time you run this, it’s going to take minutes to start as it will need to download the images for all 3 services. Subsequent start times will be in the region of a second or 2, so don’t be put off by that initial download time.

Final steps, prepare the Laravel Application.

The last steps involve a couple of things that would’ve occurred automatically had we been using the official installer.

Environment configuration file

We first need to copy the .env.example file into our own .env file. This file will not be checked into version control & we’ll have separate ones for development & production. For now, just copy .env.example -> .env

Application key & optimize

Next we’ll need to set the application key & run the optimize command. Both of these are handled by artisan, but because we have PHP and the entire Laravel app running inside of a container, we can’t just run php artisan key:generate on our local machine like you normally would— we need to be issuing these commands directly into the container instead.

Luckily docker-compose has a really nice abstraction for handling this, the two commands needed would look like:

docker-compose exec app php artisan key:generate
docker-compose exec app php artisan optimize

In plain english, the first line is saying:

Execute the command ‘php artisan key:generate’ inside the container used by the service ‘app’

And just to make it crystal clear, here’s a visual showing how those commands break down:

You’ll need this pattern any time you want to use artisan — remember the whole point of using docker is to avoid having the headaches of installing PHP versions on your local machine & this is how we get around it — by sending commands into containers, rather that running them directly.

Some other commands you’ll be running often in a Laravel project:

docker-compose exec app php artisan migrate --seed
docker-compose exec app php artisan make:controller MyController

I think you get the point by now.

Tip: create an alias like phpd that removes the need to type the full command, eg: phpd artisan migrate --seed

Once you’ve executed the two command mentioned before (artisan key:generate & artisan optimize) the application will now be ready to use — go ahead and hit http://0.0.0.0:8080 in your browser and you’ll presented with this lovely screen.

Happy developing!

Next up, modifying this setup for production.

There are already a few blogs out there covering development environments like this for Laravel, but I’ve found none so far showing how to complete the next important step — taking this environment and getting it ready for production use. I look forward to sharing that one very soon.

Resources:

• Git repo
• Git commit showing the files created in this post

Like this? If you did, and you find yourself doing any front-end work, perhaps you’d enjoy some of my lessons on https://egghead.io/instructors/shane-osbourne— many are free and I cover Vanilla JS, Typescript, RxJS and more.

In this tutorial we’re going to setup the bare minimum needed to use Preact with Typescript. No Hot-Module-Reloading or complicated Webpack configurations (we will use Webpack, but in its simplest form), just the actual bits you need to learn how to use both of these amazing tools in your projects today.

Now, Typescript already works extremely well with React (a >40kb Preact alternative) — static typing across both props & state objects makes authoring JSX an absolute pleasure. Having the compiler or your editor warn you about typos or mis-matched types as you work is something you just get used to and will be reluctant to give up when switching between libraries.

This is the problem I faced recently — I want my 3KB view renderer (Preact), but I also want my static types and awesome developer experience.

The good news is that it can be done, it just requires a bleeding edge Typescript version and the correct configuration. Here, let me walk you through it.

Step 1 — Install dependencies

yarn add typescript@next preact webpack ts-loader

# or, for npm users

npm i typescript@next preact webpack ts-loader

Note: We need to use typescript@next as this allows us to use the upcoming compiler option jsxFactory which we’ll see shortly.

Step 2 — Create a tsconfig.json file

This will configure the Typescript compiler with the options needed for Preact.

{
  "compilerOptions": {
    "sourceMap": true,
    "module": "commonjs",
    "jsx": "react",
    "jsxFactory": "h",
    "target": "es5"
  },
  "include": [
    "src/*.ts",
    "src/*.tsx"
  ]
}

Notes:

• We set "jsx": "react" to instruct Typescript to transpile JSX like <Hello /> into regular JS… But, this alone would result in something like React.createElement(...) calls which isn’t going to work for us, as Preact uses h instead.
• This is why we set "jsxFactory": "h" so that when Typescript encounters some JSX like <HelloWorld /> it will instead compile that into h(HelloWorld) which is what Preact can then use.

Step 3 — Create a webpack.config.js file

This is the minimum code needed to get this setup working. You can go crazy and do some awesome thing with Webpack, but I would suggest you start here and build up piece by piece as you need it — you’ll learn more this way as opposed to copy/pasting a 200 line config that someone else set up.

module.exports = {
    devtool: 'source-map',
    entry: ['./src/app'],
    output: {
        path: 'dist',
        filename: 'app.js'
    },
    resolve: {
        extensions: ['', '.ts', '.tsx']
    },
    module: {
        loaders: [
            {
                test: /\.tsx?$/,
                exclude: /node_modules/,
                loaders: ['ts-loader']
            }
        ]
    }
};

Notes:

• We set the extensions array on the resolve property so that we can ‘import’ or ‘require’ both .ts & .tsx files.
• The single item in the loaders array will instruct Webpack to process any .ts or .tsx files with the ts-loader plugin that we installed before. The cool thing about ts-loader is that it will use your locally installed version of Typescript by default, so there’s nothing extra we have to configure. :)

Step 4 — Create the entry file src/app.tsx

import { h, render } from 'preact';
import HelloWorld from './HelloWorld';

render(<HelloWorld name="World" />, document.querySelector('#app'));

Notes:

• on line 1 we import the render function from preact, but also the h function. We don’t need to manually call this function, but remember that Typescript will convert any JSX into h() calls, so we need it to be available in any file that contains JSX, otherwise we’ll see an error when trying to compile.
• on line 3 we’re mounting the HelloWorld component into the DOM, and passing a single prop called name . We’re doing this as a simple example of where Typescript can help — by validating your props!

Step 4 — Create the HelloWorld Componentsrc/HelloWorld.tsx

import {h, Component} from 'preact';

export interface HelloWorldProps {
    name: string
}

export default class HelloWorld extends Component<HelloWorldProps, any> {
    render (props) {
        return <p>Hello {props.name}!</p>
    }
}

Notes:

• I’ve declared the interface HelloWorldProps with a single name property here just to show how you can utilise generics when creating Components in Preact — just think of it as better propTypes. This is not a Typescript tutorial however, so we’ll leave the TS details there — just know that by providing Component<HelloWorldProps... we’re associating the interface HelloWorldProps with this HelloWorld class and this is what allows Typescript to provide type checking both inside this component and at any point in which this component is used elsewhere.
• Notice that in the render function here we get access to the component's props (as well as state) — this is an area in which Preact improves upon React :). Again though, this is not a how-to-use Preact tutorial either, so we’ll keep this bit brief.

Recap

If you’re following along, your directory should now look like the following, (although if you used NPM to install your dependencies, you won’t have a yarn.lock file)

Step 5 — run Webpack to create the bundle

Because we installed Webpack locally, we can run it in the following way.

./node_modules/.bin/webpack

Webpack will use the config file that we created earlier to load the ‘entry’ point for the app. It will then create a bundle that includes each file we’ve referenced. So in our case the entry was ./src/app — so that will be included along with the Preact Library and our HelloWorld component.

If it all worked correctly, you should see something along the following lines:

Notes:

• The file sizes in that screenshot are un-minified & un-gzipped as I didn’t want to include any extra config in this tutorial — but you can rest assured that when in production Preact really is just over 3.5kb :)

Step 6 — use the bundle in a web page index.html

Time to load it up in your browser of choice and marvel at the amazing HelloWorld component!

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document</title>
</head>
<body>
<div id="app"></div>
<script src="dist/app.js"></script>
</body>
</html>

Conclusion

Sometimes you have to do a little bit of extra work to get your favourite tools to play nicely together, but in my eyes it’s almost always worth it — especially if it boosts your productivity!. In this performance obsessed front-end world we live in I just cannot ignore a library like Preact that clocks in at only 3.5kb — but at the same time I was not willing to give up the developer experience I’ve become accustomed to with Typescript. This post shows that you can indeed have your cake, and eat it.

Like this? Perhaps you’d enjoy some of my lessons on https://egghead.io/instructors/shane-osbourne— many are free and I cover Vanilla JS, Typescript, RxJS and more.

Every terminal session is now auto-configured

Before: every single time you started a new terminal session, you needed to run the following:

eval “$(docker-machine env)”

Now: Nothing — it just works every time, in every session :)

`docker ps` will now report the docker IP when listing any addresses

Before: You needed to know your docker-machine IP address & then append the port to it. (via `docker-machine ip`, or `env` etc)

Now: The correct IP is right there in the `docker ps` command. :heart: — this means access to your services are a copy/paste away

Updating as I discover more. (looking for fixes re: permissions, volumes etc)

If you’re anything like me, you rushed onto your server the day that Let’s Encrypt entered public beta. Then because the auto service wasn’t yet available for nginx, you probably used the `certonly` command and wired up the SSL certs manually yourself…

Great, although now you’re in the situation where the cert is expired and you need to renew it. Must be the `renew` command right?

Not so easy — because your site is still online, and Let’s Encrypt needs to bind to port 80 to verify you’re the owner of the domain, you might get a horrible error stating that you should quit nginx for a moment whilst let’s encrypt does it’s thing…

Well that wouldn’t work either as the moment you disable nginx, you’ll get another error stating the domain name cannot be verified…

It’s well confusing, especially if you’re not very dev-opsy like me — but after about an hour of searching, I learned about the bundled plugin called ‘webroot’ that seemed to solve this exact problem.

So I went through all of the painful searching and came out the other side with not only my freshly renewed certs, but also this post that contains the copy/paste style solution you were looking for.

Step 1 — update let’s encrypt

You probably cloned it into your home directory right? Cool, so just move into that directory and do a git pull to grab all the latest goodies.

cd letsencrypt
git pull

Step 2 — Generate the certs again

This time though, you need to pass the `webroot` and `w` flags that point to the directory on your server that holds your files (aka, your webroot, see what they did there?). Something like this

./letsencrypt-auto certonly --webroot -w <your-web-root> --email <your-email> -d <your-domain> -d <your-other-domain>

So, for me, with my files located inside `/usr/share/nginx/browsersync/` it looked something like this.

./letsencrypt-auto certonly --webroot -w /usr/share/nginx/browsersync/ --email shane.osbourne8@gmail.com -d browsersync.io -d www.browsersync.io

Step 3— restart nginx

Let’s Encypt will dump the freshly generated files into the same directory as it did on the first run, so all you need to do now is run something like.

service nginx restart

(You can probably just reload the config into nginx if you know how to do that to avoid restarting…)

That’s it! Follow the steps and you now have another 3 months (I think) of free SSL.

New Battery

Sticky Stuff Remover

Some kind of flat screwdriver