Python is my favourite programming language, and I've always stayed firmly with the Django camp as opposed to Flask or any other gazillion alternatives. In the early days of Django (like 15 years ago) I also had lots of reservations against Rails, mostly because I was young and stupid, but also because it had too much magic. The more I've worked with JavaScript the more I've learned about good architecture and best practises from bad examples, and my views on magic have changed somewhat.

JavaScript is a fascinating language. ECMAscript 2020 is the ultimate lipstick on a pig. The core language is such an awful mess, yet the new syntax is pretty powerful and the modern tooling built around it is truly amazing and wonderful to work with. And as the tools have gotten so much better in a very rapid pace, the community is starting to get the libraries and coding conventions in a better shape as well.

Vue 3 is a great example of this. It's built totally from ground up using TypeScript, designed with an open RFC process taking feedback from the whole community, and Evan You has done a lot of work shaping the end result into something that's actually designed to be used and not only something that looks good.

The work on my new Vue 3 project template has advanced to list screens which need various list components, preferably in a form of a powerful datatable component. I had to completely drop the project for a while to get a better understanding what I'd really want here. Today I finally had an epiphany; the thing that's most wrong in the current Slipmat design are the numerous different random third-party components that even though styled to look somewhat (but not exactly) similar, they all feel different. And this exactly is my issue with glue-in frameworks like Flask as well. Even though the various parts can be easily used together, there's always something missing compared to tools like Django where everything is built to work together.

So now we get dangerously close to the infamous not invented here syndrome. If gluing up various third-party solutions yields bad results, then surely we should write all components ourselves? Well, no. Firstly, always prefer an existing ui library (like Vuetify for Vue/Material Design) over building anything yourself. Secondly, --and this is again something I realised today-- properly architectured third-party components can be not just almost but precisely tweaked to fit your design. And whenever using them, you should take the time to do that design work properly. The main problem with inconsistent Web UIs is handwritten CSS. Whenever a non-designer needs to invent their own styles, the end result will end up looking something that almost matches the thing they did yesterday, but only almost. And this is where Tailwind CSS shows again how brilliant the utility-first idea really is; there is close to zero handwritten css needed for most Tailwind projects which automatically restricts you to a relatively small amount of professionally curated choices. The end result looks automatically not-very-bad and with some tweaking it’s not hard to get absolutely spot-on. (To be fair, it’s not easy either, but unlike trying to manually come up with CSS, it’s way easier!)

After I watched Adam Wathan build this select component, I was convinced that this would be the way I should build the few components (button, toggle-switch, modal, toast, data table / list component, datepicker, tag input) I need for the Slipmat rewrite.

(Yes. NIH. I'd love to use some third-party library here but at the moment there just aren't too much to choose from for Vue 3 and Tailwind.)

The first iterations don’t need to be anything too fancy so I’m confident that building all of these from scratch instead of trying to modify third-party alternatives won’t be an issue. I’m also fully prepared to switch to using @tailwindui/vue or some other library in the future if maintaining these eats too much time. Just to get a feeling of what the API would maybe feel like I created an experiment project and pushed it to GitHub (not GitLab because on GH I get Dependabot updates automatically).

So this story has been a bit of a rambling journey from back in the early days of Web frameworks to Vue 3 and Tailwind CSS. What I’m finding common between all these projects is the meticulous attention to detail regarding almost every aspect of the tool, especially to API design. Great tools aren’t born by accident, they are engineered. And after working with JavaScript for few years now I’m starting to appreciate the metaprogramming powers of Python which makes it possible to write super clean —and somewhat magical— APIs. A good amount of magic really makes a difference in developer experience when it’s done right. I still do think that having a pluralization engine that automatically fetches one Octopus and many Octopi is way too much but I also do appreciate the attention to detail in Rails the more I get to see language restricted not-so-beautiful designs in JavaScript land.

So the lesson of the day: invest in API design and the most value from magic comes from those situations where you can't see it.

1. Rename Git Master Branch

First, rename master and push the change to origin, then update local references to this new name. (I'm using trunk here as the new name but you can use main or whatever you wish. Just change the commands accordingly.)

git checkout master
git branch -m master trunk
git push -u origin trunk

git branch --unset-upstream
git branch -u origin/trunk
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/trunk

2. Change GitLab Default Branch (And Delete master)

Navigate to Settings > Repository and set the new default branch. (In GitHub you'll find the same setting under repository Settings > Branches.)

Lastly you may want to delete the old master branch but you need to remove protected branch status from GitLab before being able to do that. Go to Protected Branches on this same Settings > Repository page and Unprotect the master branch if it's protected. (Don't forget to add the same protections back to the new branch!) Now we can delete the old master branch:

git push origin --delete master

Bonus: Change Default Git Branch For New Repositories

Since Git version 2.28 you can easily set the default branch name for all new repos with a simple command:

git config --global init.defaultBranch trunk

Congrats for participating in making the word just a little bit better place for all of us!

Shaping Up

I discovered Shape Up originally via Adam Wathan who posted absolutely brilliant Twitter thread about becoming a succesful independent maker. It took me a wihe to manage to actually read it, but now that I finally did, it left me with some good ideas about shaping up (pun intended) my own work practises.

Shape Up is a very Basecamp-y look on modern development workflow and work practises. It narrows down on an idea of a 6-week work cycle where the team works on a pre-planned (shaped) project with external phases for planning and also for bug-fixing (what they call cooldown). Reading this felt really good as it is very similar what I've been doing with many teams of various sizes for a long time now.

I've found out that with most agile teams the idea of a 10-day sprint that inludes design and retro phases are just way too short. It forces the work to be planned and scheduled too much from the top down and leaves the team very little time for independent organization. If the work is instead planned (shaped up) beforehand with a smaller and more experienced team, and there is a separate bugfixing (or cooldown) period after the actual work phase (which is longer than two weeks) the probability of succesful delivery grows drastically.

This is very interesting topic for me and I'll propably write more about it in the future. With some new inspiration from these ideas I reorganized my near future personal work in a new way. I converted my monthly plan from two sprints into a one cycle with a proper Iteration Plan (idea stolen from VS Code team) that has just one properly shaped and planned goal and clear dates for work phase. My cycle lasts for three weeks after which there is a one-week cooldown for bugfixes and planning for the next cycle. This method lets me keep monthly release cycle and hopefully allows me to actually ship something every single release. I may report back on the success of this model in the future.

New Vue 3 + TypeScript Project Template

For my end goal of shipping a totally new Vue 3 + TypeScript powered frontend for Slipmat users and artists I need a good and tested base for which to build on. To experiment with this I started a new project from scratch to remake the current admin views which have become a bit of a dumpster fire.

I'm using Tailwind UI components as a base which makes getting started really easy and fast. Unfortunately all the components are based on very bright color themes so I've had to come up with my own dark color scheme as Slipmat needs to be dark by default. I spent a week with the initial design and refactoring some old API views to get some basic dummy data for developing. The end result looks pretty good as a starting point, I'm sure the final product will work out great. (This is just a proof of concept after all!)

Vue 3 is now in RC phase and using it with TypeScript feels really solid already. The tooling (devtools in particular) is lagging a little bit behind but it's early days still. I've got the project base pretty much nailed, it has fully automated CI/CD pipeline with end to end tests with Cypress and Mirage JS with coverage monitoring that fails the build if coverage drops below 80%.

I've also tried to keep everything as lean and as close to native JavaScript as possible. Most of the usual go-to libraries have had a tough screening and for example Moment.js (70k) had to go in favor of Day.js (2k). So far I've managed not to load lodash either, although it might come back at some point as practicality beats purity. I might do a write up of these most used third-party libraries as well when I'm starting the final production projects.

Here's the full list of my current dream stack that powers the new project:

• Vue 3 (w/ vue-cli)
• TypeScript
• Tailwind CSS
• Cypress for e2e-tests
• Mirage JS for dev and test backend

JavaScript Search Engines

Proper search is something that I've never got time to build for Slipmat yet but especially for admin tools it's very important. We do run Elastic on our backend stack but I wanted to investigate if I could whip up something very fast and totally in-browser so I studied few JavaScript search engines.

Turns out there aren't that many serious contenders. There's Fuse.js which is great for small datasets (say less than few thousands of objects). I've used it in the past for some projects but I wanted something a bit more serious for this. There's also Lunr.js and Elasticlunr.js both of which are loosely based on Solr. These are serious search engines with lots of options for tweaking the results and proper indexing.

I ended up picking MiniSearch which is a tiny (6k min+zip) yet "proper" and modern search engine that has no external dependencies and can do all kinds of nice things like fuzzy matching, auto suggestions, field boosting and realtime index updating. It can also export and import the built index which makes the initialization very fast. I'm testing the system with a 2Mb json file that has few thousand latest instances of about every model one might want to search (offline) from the admin dashboard. The biggest overhead comes from downloading this first json. Initializing the engine takes about 300ms but when you save the index it shrinks to about 1,5Mb and initializing that only takes about 50ms. As an initial proof of concept the simple pre-warmed and cached json works well enough though.

I'm not yet sure if having a offline-capable frontend-only search is worth it when everything is already indexed in Elasticsearch but this was an interesting one-day experiment in any case. Here's the search in action:

Okay so this weeks notes were a bit on the long side but hey, it's been a while. But let's try to do this again next week! In the meanwhile, find the RSS-feed and @Uninen on Twitter :)

Vue has a somewhat mixed TS story. On the other hand most notable packages support it well but then there are also large painpoints like Vuex that can make your life miserable. Upcoming Vue 3 is completely rewritten in TypeScript which will improve TypeScript support hugely. In attempt to future-proof a rewrite of a large existing Vue app, I decided to start gradually typing it with TypeScript. Here are some of the initial notes from my experience.

(Disclaimer: even though I'm an experienced Vue developer, I'm a complete TS-newbie so YMMV.)

The Unbearable Lightness of Starting Slow

Problem with most TypeScript tutorials and simple examples is that they expect you to either start from scratch or completely convert all of your code to TypeScript from the very first step. For an existing codebase, that's obviously not going to happen. I would also personally advice against it even if there were tons of tests and all the time in the world to do it, especially if you're new to TypeScript.

The great secret of TypeScript is that you can start as small as you like and add typings gradually. By doing it this way you'll probably find some problems with your existing code and get the chance to refactor it properly as you move forward. Granted, you won't get the full benefits of TypeScript before you reach a certain critical point of typing completeness, but starting it small will cost you almost nothing so its very easy to get started. Life with legacy codebases is all about compromises and this path will at least give you a chance for better future.

Step 1: Initial Installation

If you're vue project is created with vue-cli, adding typescript looks easy: just vue add typescript. Problem is, the defaults may not be that good for you and you should know what they mean. Here's what I answered to the installer questions:

Use class-style component syntax? ❌No

By default this plugin suggests you to use class-style components which are an easy way to get started with Vue and TypeScript. Class based api was supposed to be the future of Vue, but the class syntax is in many ways problematic and if you plan to upgrate to Vue 3, you will want to consider composition api instead.

Note that many tutorials and existing TypeScript code for Vue uses class syntax. If you opt out here you have much less refactoring to do with your JavaScript and you are more future-proof with Vue 3, but you will also lose a big chunk of the examples and tutorials out there right now.

Use Babel alongside TypeScript (required for modern mode, auto-detected polyfills, transpiling JSX)? ✓ Yes

If you have an existing project where you use Babel, you'll definitely want to keep using it with TypeScript as well.

Convert all .js files to .ts? ❌No

This is the most problematic suggestion of them all. Sure, if you're converting a small app with five files for fun, do it. But if you're adding TypeScript to a larger project, definitely do not rename all of your JavaScript files in one go, that's just asking for trouble.

Allow .js files to be compiled? ❌No

As the documentation on the whole plugin is very thin, I don't exactly know what this option even means but I assume it's one more toggle to help you bruteforce TypeScript into your project. By default any JavaScript code will stay JavaScript and only .ts files and script tags with lang="ts" will be compiled, and that's the way you'll want it to be when starting gradually.

Step 2: Cleaning Up

The "helpful" installer will modify your existing code so you'll need to do a bit of cleanup before getting back to business. First, you'll want to delete the re-appeared src/components/HelloWorld.vue as I'm quite sure no one is actually using that in a real project (right??). You also want to fix the havoc in your src/App.vue while you're at it. The main.js is now renamed to main.ts. This is a good change as it reminds you immediately that this project uses TypeScript even though most of the files might still be JavaScript.

The newly added tsconfig.json includes somewhat strict settings that may or may not work with your project. The stricter the rules, the more benefits you get from TypeScript, but on the other hand the stricter the rules, the harder it is to make your existing code valid. For me one of the first steps with an existing project was to disable strict checking. This allowed me to gradually add typings to complex files without spending hours and hours in debugging or adding the file full of ignores. Note that by loosening the checking you will lose some of the most powerful gains you could have from your editor and TS in general so evaluate yourself if you can leave it on or not.

(For example, with strict checking on, when editing a method inside a Vue component, the editor will know that this refers to a specific Vue instance. This is super powerful when it works. When strict checking is disabled, this inside of a component method is inferred as any type which will not help you at all.)

I would not tweak tsconfig too much more before you understand better the challenges in your specific project. Give yourself time to test and experiment before committing to any specific rule.

Step 3: Start Adding Typings

Now you are ready to start adding your first types! I'd suggest to start in a file that is large or otherwise not so easy to read at a first glance -- this is where you'll get most gains.

This is not a tutorial on TypeScript itself, you'll find plenty of them elsewhere. The migrating from JavaScript document is a good read and Using TypeScript with Vue Single File Components was very helpful to me as well. Vue + TypeScript Cookbook is a brilliant source of practical advice and it also points out some of the long standing issues such as the problems with Vuex.

Oh yes, Vuex. Have a plan for Vuex. Almost all larger projects use Vuex and for example the mapState helper, so you'll immediately be in a world of trouble as Vuex does not have proper TypeScript support and no simple solution has been found by the community. This does not mean that you can't use Vuex with TypeScript or that there are no solutions. It just means that there are no good universal solutions. You need to experiment and evaluate which of the dozens of proposed workarounds works best for you. And know that if it at some point stops working in your specific edge case, you're alone with your problem as there is no officially supported way. This obviously sucks big time, but there is at least some light at the end of this tunnel as Vue 3 will eventually bring proper TypeScript support to Vuex as well.

Try not to ignore code. Alarm bells should ring if your TypeScript code starts gathering // @ts-ignore-lines more than actual refactoring. It's the same with linting: the point is to make your code better, not to work around your tooling. Sure, there are situations where practicality beats purity but make a mental note for yourself to keep those situations exceptions. If you find a file too hard to convert, just leave it be until you or your tools become smarter.

There are a couple of good rules of thumb you should keep in mind. First, all new code should be typed. This is kind of obvious but also easy to forget. Add documentation and processes in place to make sure that from now on, all new code in the project is written in TypeScript instead of JavaScript. You can help this process with CI scripts and other tools: ban adding .js files and if you have tools that generate new files, convert them to generate .ts.

Secondly, try not to change too much in one go. It's very easy to stumble down into the rabbit hole and use hours and hours adding typings with very little practical gains. As you learn more and as Vue world matures, you'll be getting more and more out of TypeScript. And then some day when you understand more about your project and the tools, you'll see more clearly when it is the right time to take the last step of converting all the remaining code to TypeScript. Remember, cleaning up your codebase is not a race, it's a neverending journey.

Things Will Break -- It's a Good Thing

The thing with TypeScript that makes it both helpful and painful at the same time is the fact that it's much more unforgiving to mistakes that you've used to with JavaScript. My very first steps with TS in a real world project involved several hours of debugging a file that would not compile no matter what I did. Turns out it was due to a missing import in a legacy method that was never called. You'll never find out things like this in JavaScript but they will bite you with TypeScript as soon as you turn it on, so be mentally prepared.

Legacy code is difficult in many ways and hunting down new bugs that previously weren't there can feel frustrating. But remember that this is exactly why you want to use TypeScript in the first place: to see and fix those bugs early. It's very likely that your old production code is relying on a bug you didn't even know was there and turning on TypeScript will now break that code. Learn to embrace these growing pains because fixing them will make your code better and keep your productivity high in the long run.

Gridsome is a JAMstack tool which means that features like commenting need to be implemented either as a third-party solution or by using a separate backend functionality be it serverless functions, a traditional REST backend or something similar. Firebase is an interesting app development platform startup that was aquired by Google in 2014. What makes Firebase intresting for this kind of applications is its realtime database and hosted pluggable authentication system. Google offers a fairly generous free tier for the services so testing it out for a personal project like this is costs you only your time.

I'll write more in depth about technical details later but for now, I'm happy to get this thing published. The biggest lesson learned here was that as with any tehcnologies, even though the 2 minute demo seems really clean and easy, most real worl implementations need to focus on details that are hard to get right if you care about user experience and security.

(Obviously, this first implementation is very unpolished and not feature-complete, but it should work, that's the most important thing for now.)

(Note: if you happen to use some other editor, you should be able to install graphiql-explorer by adding it in the dev server config with configureServer-hook.)

The 1-minute install

1. Install the vscode-graphiql-explorer-extension.
2. In your repository root, while your development server is running, generate a GraphQL schema for the plugin with following command: npx get-graphql-schema http://localhost:8080/___graphql > schema.graphql (the first part of the URL should be your development server URL). You might want to add schema.graphql to gitignore as well.
3. Profit!11

You can now use the GraphiQL explorer inside your VS Code. Run Explore schema with GraphiQL command to see it in action.

Notes

• The two other commands added by this extension don't currently work with the custom Gridsome GraphQL blocks inside -vue files. What you can do is either copy the code in an open explorer window or open it in a new file and then run the explore-command. I opened a ticket for fixing this, it seems that it might be fixed quite soon.
• graphiql-explorer is bundled with Gatsby and according to Gridsome developers, they might switch to using it in Gridsome as well. There's actually an old ticket about this, too.
• Shout-out to @eunjae_lee for leading me into this rabbit hole :)

There are tools like Pablo for creating these images online. Recently I've switched to creating them manually with Pixelmator but I've long been looking for a Web-based solution that could be integrated better with my other blogging workflows.

Two days ago I happened to stumble on to ZEIT Now's blog post Social Cards as a Service where they dogfood their own serverless platform by building a simple image generator tool that uses Puppeteer to render the images. I immediately dove in to the source code hoping that I could modify it to my own needs but it looked way too complicated for my taste. (In other words, I didn't understand most of it.) The UI got me thinking that building a simple framework around Tailwind would probably be super easy and would allow lots more control. So I sat down for two evenings and came up with Open Graph Image Builder.

This is still a work in progress and I'm not sure how far I want to develop this but so far it has been a fun little project.

The Toolchain

My absolutely favourite frontend tool for simple projects like this has been Vue CLI. Problem with that is that as soon as you start thinking about publishing something, you'll have gazillion things to glue together and configure before you have a production-ready site. (I should probably invest some time into a proper cookiecutter template...) This exactly is why I recently wrote Tulip, a simple one page starter template for Gridsome (which is just Vue with some JAMstack flavor).

Tulip ships with Tailwind CSS preconfigured so I was immediately ready to build something interesting.

The third weapon of choise was ZEIT Now. I've been following their journey for a long time because of Simon Willison but never actually tried the platform. As it was their inspiration that led me to this path it was only appropriate to try out the service with this project. The first installation and publishing workflow via the deploy button in Tulip repository was unbelievably easy, even easier than Netlify if it's even possible. (Although I did have an issue with GitLab import. It didn't work so I pushed my code in GitHub instead and after that everything has been smooth sailing.)

Example output:

To Be Continued...

The project is just getting started and I want to learn the ZEIT platform a bit more to be able to write about it better. I'll also probably implement a proper backend rendering for the images so it'll be a bit more useful in practise.

In part 2 of this series I'll dive deeper into the code, going through some of the challenges and design decisions along the way.

In the mean time, check out the project source code and follow me on Twitter!

Adding a New GraphQL Property

At the heart of a Gridsome site is a GraphQL data layer that you can use and manipulate in development mode. Gridsome fetches any sources you define into this GraphQL storage in development mode and during the build process writes the data into static files as instructed in your configuration.

The naive way of importing any data into Gridsome just adds it into the storage and it then respectively gets published as you build the site. A super simple way to implement draft functionality is to simply add an attribute to your data object and then filtering by this attribute when building the site.

Add the following javascript in a file called gridsome.server.js in the root of your Gridsome project:

module.exports = function(api) {
  api.loadSource(store => {
    if (process.env.NODE_ENV === 'production') {
      const posts = store.getContentType('Post')

      posts.data().forEach(node => {
        if (node.published !== true) {
          posts.removeNode(node.id)
        }
      })
    }
  })
}

(Change the Post ContentType to match whatever your source plugin typeName has been configured to in gridsome.configjs plugins section. The default for source-filesystem-plugin is FileNode.)

Now, when you run gridsome build, the API that loads your sources at build time filters out each post that hasn't got a published-attribute that evaluates to true. (Note that if you have a blog with lots of content and you don't want to add a new attribute to all of them, you might want to reverse the logic, for example to if (node.draft !== true). I like to explicitly mark published posts, YMMV.)

For Markdown and Front Matter content you can now add published: false to your post meta to be able to filter out draft posts in production. (Modifying other content sources is left to the reader.)

1. Publish Weekly Blog Posts

On this one I have to take a somewhat late start as January almost flew by already, but I'm targetting to write to this blog at least ~50 new posts this year. I love writing and I do write quite a lot but I've lost the habbit of doing it in the form of blog posts -- and I want to get that habbit back.

I have tons of stuff in various draft posts and even more ideas about things to write about and I'm looking forward to make myself find a good publishing rhythm after a long hiatus. So stay tuned! :)

2. Release / Document More Hobby Projects

One of my biggest problems is that I love digging into new technologies and starting something but then never actually getting anything published (nor documenting the journey). I want to learn to be better especially in the documenting part as I know that it's where I can contribute the most (compared to actual coding, for example).

3. Release At Least Two Serious Side Projects

I've been working on a side project called Slipmat.io for almost four years without actually committing to getting it properly published. I've also sat on a good idea (in my opinnion) without moving it forward for a couple of years now and I really want to get both of these projects in a better place.

While Slipmat is more of a hobby project, the second idea is something that could actually be turned into a proper SaaS business if done correctly. Both of these require a lot of time to complete so I really need to learn to split things up in smaller iterations and move faster if I'm going to pull this off. I'll be documenting both of these journeys here, so again, stay tuned.

4. Attend To a New Tech Conference

I've been attending to Python-related conferences since 2007. This year I want to find a new non-Python conference to find different perspectives into the world of modern software development.

5. Fix My Tooling

When I was younger, I was constantly obsessing over my tooling to make my workflows faster and better. Lately I've noticed that my hatred towards computers and technology has grown so big that I'm usually just happy if my tools even start. The Web tooling has gotten so big and complex that it takes serious time and effort to keep everything up to date -- not to mention of trying to optimize things.

I want to make some time and rebuild some very basic stuff (starting with dotfiles) around my personal tooling, document them better and start to get back on top of things again. Continuous improvement, Kaizen, is something that I'm really passionate about so this is again a goal that is hopefully going to lead to some interesting and fullfilling paths.

So, there are my five fairly ambitious goals for 2020. Now, it's time for some action!

Use self.stdout instead of print in management commands

You should never use print inside Django management commands as they have a special self.stdout method that makes testing easier. This method frustratingly takes slightly different arguments than print, but it also has more features like styling. Here's how you would do a simple row of dots that grows iteratively:

self.stdout(".", ending="", flush=True)
self.stdout.flush()

Note the flush(). This is wat forces the output to be shown to the user before the script finishes. And the same with print:

print(".", end="", flush=True)

Both self.stdout and print will add newline to the output by default but you can disable that by explicitly setting the ending as an empty string. And when you flush your output manually, you'll get nice and interactive console output for your management commands -- voilà!

(Btw. If you have ever wondered about ENV PYTHONUNBUFFERED 1 in some of the Docker images for Python, this is why; disabling output buffering makes reading Docker logs way easier.)