Vincent Prouillet: Developer & Entrepreneur

Releasing Zola 0.12

Unknown — Fri, 04 Sep 2020 00:00:00 +0000
A brand new Zola</a> version is out! Zola is a flexible static site engine.
This new version doesn't contain a lot of new changes, summer and global pandemic not being the most productive environment - at least for me.
The main improvement of this release is completely changing how zola serve</code>. Before 0.12, it used to write the whole site to disk and on changes try to figure out what changed and the minimum things we need to rebuild. It sounds good in theory but in practice was very buggy as Zola is pretty flexible: you can access the site content from any template (for example there could be a box with the most recent 5 articles on every page). And, well, it was trying to be too smart.
With 0.12, the rendered content will be stored in a HashMap in memory instead. Only the HTML content is stored in that HashMap, the assets stay on disk. When anything changes in a template or in a Markdown file, we rebuild everything. This is slower than the previous mechanism but has the advantage of always producing the correct output. The downside is that it is slower: making a change to a Markdown file on the Zola documentation used to do a rebuild in 8ms and would now take 200ms. Still fast enough for the majority of cases. If you have a huge site and the rebuild is now too slow, you can use zola serve --fast</code> that rebuilds only the section or page that changed and gets you back to the 8ms rebuild time. Hopefully this approach works better for most people!
There are a few other changes that you can see in the CHANGELOG</a>.
The next version will be focused on finishing the multi-language story with a full i18n integration based on Fluent</a> as well as adding some options to he Markdown rendering, such as smart punctuation.


Using CSS modules with Sass, Webpack and TypeScript
Unknown — Fri, 24 Jan 2020 00:00:00 +0000
A few months ago, I mentioned in my articles about setting up Webpack with TypeScript (part 1</a> and
part 2</a>) that CSS modules would be a nice addition to it. Here we go!</p>
What are CSS modules?🔗</a></h2>
One common issue for anyone writing CSS is specificity</strong>. As a site grows, the number of CSS rules and classes grow.
This makes it easy to accidentally re-use an existing class name by inadvertence and wonder why your text is now red.</p>
CSS modules are pretty simple. Let's start by writing CSS/Sass/Less as you would normally do:</p>
.my-class </span>{
</span>   </span>color</span>: </span>red</span>;
</span>}
</span>.title </span>{
</span>   </span>font-size</span>: </span>2</span>rem</span>;
</span>}
</span></code></pre>
You can then import the file in your .js</code>/.ts</code> variable (like import styles from "_style.scss";</code>) and access the class names from it: styles.title</code>.
Not very impressive but if you look at the source of your HTML page you will notice the class is some random combination of letters and numbers.
This is the powerful part of CSS modules: each class gets its own unique name which means that there cannot be specificity issues anymore.</p>
There are a few other ways to solve the specificity issues:</p>

use something like BEM</a>, which requires discipline</li>
use a CSS-in-JS library like emotion</a>, which is more complex and has lower performance than alternatives</li>
hope for the best</li>
</ul>
Adding CSS module to the Webpack boilerplate🔗</a></h2>
Turns out enabling them is really easy! The only tricky part is, as some might have guessed from the example above, ensuring
TypeScript does not error when loading the Sass file. Thankfully, a loader exists to automatically create definition file from CSS files:
typings-for-css-modules-loader</a>.</p>
Let's go quickly through the main changes needed to the Webpack configuration:</p>
-          // Translates CSS into CommonJS
</span>-          "css-loader",
</span>+          {
</span>+            loader: "@teamsupercell/typings-for-css-modules-loader",
</span>+            options: {
</span>+              banner: "// autogenerated by typings-for-css-modules-loader."
</span>+            }
</span>+          },
</span>+          // Translates CSS into CommonJS with modules
</span>+          {
</span>+            loader: "css-loader",
</span>+            options: {
</span>+              modules: {
</span>+                mode: "local",
</span>+                localIdentName: '[local]--[hash:base64:6]',
</span>+              },
</span>+              localsConvention: "camelCase"
</span>+            }
</span>+          },
</span>
</span></code></pre>
We go from a plain css-loader</code> to one with modules enabled with a local</code> scope and where the generated classes are still readable.
We also tell the loader to camel case the classes in order to satisfy the various linters.
Lastly, we set the @teamsupercell/typings-for-css-modules-loader</code> above</strong> the css-loader</code>, the position is important.
There are other changes in the commit, such as ignoring all generated files, that are pretty straightforward.</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/9786130bf283d47af1d1945ac66679a0529254c4</a>.</p>
Anything missing?🔗</a></h2>
Now that we have CSS modules in place, the only thing I consider missing is Storybook</a>. This is
unlikely to get an article as it is pretty easy to follow the instructions to install it though.</p>
Are there any amazing libraries/Webpack plugins I'm missing out on?</p>


Tera v1 is here!
Unknown — Sat, 07 Dec 2019 00:00:00 +0000
Tera is a template engine inspired by Jinja2</a> and the Django template language</a>.
It is also similar to Twig</a> and Liquid</a> if you are coming from PHP/Ruby.</p>
The last release, 0.11.20, was released back in November 2018 and the first v1 alpha was released in January 2019. During 2019,
the Zola</a> static engine has been keeping up with each Tera release and has therefore been tested quite a bit.</p>
If you want to see the TL;DR of all the changes since 0.11.20, you can have a look at the changelog</a>.</p>
In most cases, the upgrade to v1 should be painless: unless you are using the error-chain part of Tera errors, it might
even work without any changes.</p>
Before going further, a huge thank you to everyone that contributed</a>.</p>
Let's look at some of the main changes in a bit more detail now.</p>
Error handling🔗</a></h2>
Error handling is a hot topic</a> in Rust and has been for quite some time.
At the time of 0.11, error-chain</a> was the recommended approach but pretty much as
soon as I ported all of my code to use it, failure</a> became the go-to crate. Since then,
some of failure</code>'s features made their way into the standard Error</code> trait including the one I am using: the source</code></a> method.</p>
I have pretty much given up on any error handling crate for the time being and just use std::Error</code> for everything, including in this new version of Tera.</p>
Traits for filter, tests and functions🔗</a></h2>
Previously, the type for each was a simple function. It has now been changed to a trait, allowing for each of them to have a context, for example.
Zola, for example, uses structs for some of the functions in order to hold the site data. The trait is automatically implemented for the previous function
type so if you had defined your own they should continue to work, as soon as you change their arguments to be borrowed instead of owned.</p>
Whitespace management🔗</a></h2>
You can now use the same whitespace management as Jinja2 in Tera:</p>
hello
</span>{{- </span>username </span>-}}
</span>!
</span></code></pre>
will render hellovincent!</code> if username</code> is vincent</code>. Please see the documentation</a> for more details.</p>
Increased rendering performance🔗</a></h2>
The whole rendering code has been rewritten to be more performant.</p>
The bottleneck is still converting the context to JSON since it needs to clone the data.
This is unlikely to change until we move to a borrowed approach but I do not know how to approach that. If
anyone can figure out a way to solve this issue and still be ergonomic, that would be amazing; please chime in on the related issue</a>.</p>
How does it compare with other Rust template engines? There is a benchmark</a> testing just that.
Before showing the results, it is important to understand the difference between the compiled templates and interpreted templates:</p>

compiled template engines: askama</a>, horrorshow</a> and most of the ones
in that benchmark are generating Rust code through macros. The big upsides of this are performance and being able to typecheck your templates.
The big downsides are compilation time and not being able to handle dynamic templates: you cannot render an arbitrary template file.</li>
interpreted template engines: Liquid</a>, Handlebars</a> and Tera are in this category.
They are not going to be as fast or type-safe as compiled one but can run any templates you throw at them.</li>
</ul>
For example, a static site engine could not work using a compiled template engine as users define their own templates, add arbitrary data and extend other random existing templates.</p>
I've grouped the table output of the templates benchmark (done with criterion.rs</a>) depending on the template engine type.
The benchmarks have been ran on a 2018 Macbook Pro.</p>
Big table benchmark🔗</a></h3>
This is running a for loop with a context being an array of length 100 with each element being another array of length 100.</p>
Big</span> table/Askama        time:   </span>[</span>624.98 us 643.77 us 663.40 us</span>]
</span>Big</span> table/fomat         time:   </span>[</span>228.47 us 230.94 us 234.08 us</span>]
</span>Big</span> table/Horrorshow    time:   </span>[</span>357.87 us 371.52 us 385.84 us</span>]  
</span>Big</span> table/Markup        time:   </span>[</span>294.43 us 302.90 us 313.99 us</span>] 
</span>Big</span> table/Ructe         time:   </span>[</span>586.48 us 609.61 us 638.02 us</span>]
</span>Big</span> table/Yarte         time:   </span>[</span>286.75 us 311.03 us 334.20 us</span>]
</span>Big</span> table/write         time:   </span>[</span>353.75 us 370.98 us 391.61 us</span>] 
</span>
</span>Big</span> table/Tera          time:   </span>[</span>3.5811 ms 3.6997 ms 3.8292 ms</span>] 
</span>Big</span> table/Liquid        time:   </span>[</span>12.890 ms 13.113 ms 13.366 ms</span>] 
</span>Big</span> table/Handlebars    time:   </span>[</span>83.598 ms 86.947 ms 90.391 ms</span>]   
</span></code></pre>
As you can see, this is a bad case for interpreted template engine. Tera is the fastest among them but is still up to 10x slower than some compiled engines.
The result from Handlebars are particularly odd: I do not see why it would be 23x slower than Tera.</p>
Considering those results, you should probably use a compiled template engine if you are trying to render some context
requiring a lot of allocations like in that benchmark.</p>
Teams benchmark🔗</a></h3>
This is rendering a template with a small array of structs as context, a more realistic average workload.</p>
Teams/Askama</span>            time:   </span>[</span>1.1503 us 1.2120 us 1.2800 us</span>] 
</span>Teams/fomat</span>             time:   </span>[</span>502.20 ns 512.54 ns 524.81 ns</span>] 
</span>Teams/Horrorshow</span>        time:   </span>[</span>466.38 ns 469.09 ns 472.31 ns</span>] 
</span>Teams/Markup</span>            time:   </span>[</span>403.39 ns 408.75 ns 416.11 ns</span>] 
</span>Teams/Ructe</span>             time:   </span>[</span>963.43 ns 976.63 ns 989.98 ns</span>]
</span>Teams/Yarte</span>             time:   </span>[</span>766.24 ns 782.78 ns 800.46 ns</span>]
</span>Teams/write</span>             time:   </span>[</span>756.18 ns 770.13 ns 784.21 ns</span>] 
</span>
</span>Teams/Tera</span>              time:   </span>[</span>8.8657 us 8.8969 us 8.9288 us</span>] 
</span>Teams/Liquid</span>            time:   </span>[</span>12.858 us 12.909 us 12.960 us</span>] 
</span>Teams/Handlebars</span>        time:   </span>[</span>70.150 us 75.716 us 81.926 us</span>]
</span></code></pre>
Tera is again the fastest interpreted template engine, but the numbers are small enough that any engine will do the job.</p>
Glob patterns now supported🔗</a></h2>
You can now pass patterns to Tera::new</code> like templates/**/*{html,xml}</code> to load exactly the type of files you want.</p>
A builtins</code> feature🔗</a></h2>
The number of dependencies started to grow quite a bit as filters and functions were being added.
From 1.0.0</code>, a new active-by-default feature named builtins</code> has been introduced. If you disable it, Tera will only
depend on the crates needed for parsing and rendering and all the filters and functions that were depending on those
dependencies will not be present anymore.</p>
Known issue🔗</a></h2>
Due to a bug in pest</a>, the parser generator used by Tera, some template parsing might timeout. There
are more details in the issue</a> but since the pest contributors are working on v3,
it doesn't seem worth it to hold on releasing Tera 1.0 for an unknown amount of time until its release.
This issue was found while fuzzing but I've been running into https://github.com/rust-lang/rust/issues/66140</a> when trying
to run the fuzzer again on OSX.</p>


Setting up a React+TypeScript frontend with Webpack — Part 2
Unknown — Fri, 01 Nov 2019 00:00:00 +0000
In this article, we are going to turn our local environment setup</a> into
a production-ready setup. Thanks to improvements in recent Webpack versions, it is now straightforward.</p>
NODE_ENV=production in Webpack🔗</a></h2>
The majority of JavaScript projects use the NODE_ENV</code> variable to enable optimizations and remove debug code. If you need
to support Windows, setting an environment variable directly in the script the UNIX way is not going to work. You can install cross-env</a> to handle cross-platform environment variables.
The script in that case is "build:prod": "cross-env NODE_ENV=production webpack"</code>.
Again, if you do not need Windows support, simply remove the cross-env</code> from the script.</p>
Now there are two ways to proceed:</p>

split the configuration in multiple files and merge them with something like webpack-merge</a></li>
keep everything in one file and use JavaScript to toggle things</li>
</ol>
I prefer the second approach as I find it more readable and doesn't require additional dependencies. You can judge for yourself
by looking at the final result</a>.</p>
As mentioned before, Webpack has been making things easier. With the introduction of mode</a>, it is easy
to get a production-ready bundle:</p>
diff --git a/webpack.config.js b/webpack.config.js
</span>index 53c39f2..b4d6e11 100644
</span>--- a/webpack.config.js
</span>+++ b/webpack.config.js
</span>@@ -4,9 +4,11 @@ </span>const HtmlWebpackPlugin = require("html-webpack-plugin");
</span> const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
</span> const { CleanWebpackPlugin } = require("clean-webpack-plugin");
</span> 
</span>+const isProd = process.env.NODE_ENV === "production";
</span>+
</span> module.exports = {
</span>   context: __dirname,
</span>-  mode: "development",
</span>+  mode: isProd ? "production" : "development",
</span>   entry: {
</span>     app: "./src/index.tsx"
</span>   },
</span></code></pre>
Just changing the mode will get us a minified output: you can check it by running build:prod</code> yourself.</p>
Looking at the minified code, we can see that the sourcemap is embedded in the file still.
The best option for production environments</a>
is source-map</code> which we can set conditionally on the isProd</code> variable: devtool: isProd ? "source-map" : "eval-source-map",</code>.
Running build:prod</code> again will now properly create a separate file ending in .js.map</code>.
Remember that the sourcemap files should not be accessible by anyone other than you and your bug reporting app.</p>
Lastly, the HMR from Webpack is injecting some code in the bundle that we do not want in our production bundle. We can disable it easily:</p>
diff --git a/webpack.config.js b/webpack.config.js
</span>index af5fd2f..63272fd 100644
</span>--- a/webpack.config.js
</span>+++ b/webpack.config.js
</span>@@ -58,6 +58,6 @@ </span>module.exports = {
</span>       async: false
</span>     }),
</span>     new CleanWebpackPlugin(),
</span>-    new webpack.HotModuleReplacementPlugin()
</span>-  ]
</span>+    isProd ? false : new webpack.HotModuleReplacementPlugin()
</span>+  ].filter(Boolean)
</span> };
</span></code></pre>
The commit is https://github.com/Keats/webpack-react-typescript/commit/4527184f2d7a49447451774b1bf5cc8d4cb3c1e5</a>.</p>
Splitting chunks🔗</a></h2>
In our current situation, we generate a single file for the whole app: it clocks in at 132KB before gzip.
This means that every time someone changes anything in the codebase, the full bundle will be invalidated and re-downloaded by every users.</p>
There are two approaches to splitting the chunks:</p>

bundle splitting</strong>: separating into fixed bundles, for example putting dependencies into another bundle</li>
code splitting</strong>: splitting your own code into multiple bundles loaded on demand</li>
</ol>
Bundle splitting🔗</a></h3>
The easiest bundle splitting strategy is to create a vendors</code> bundle containing all dependencies. In our case we currently
only have react</code> and react-dom</code> but it will inevitably grow and, unless you are upgrading dependencies every day, will not
change very often. Dividing the bundle does not change anything for first-time users as they will have to download all files but
repeat users will only download the bundles that changed.</p>
Webpack comes with a built-in option to split everything coming from the node_modules</code> folder to another bundle: optimization.splitChunks.chunks</a>.
Setting it to "all"</code> will produce a new JavaScript file with a name starting by vendors~app</code> in the output directory weighting 131KB while the app bundle shrank down to 1.9KB.
If you run build:prod</code> again after making a change to index.tsx</code>, you will notice the hash did change: we need to ensure the hash
is done on the content rather than the build. In practice this means changing [hash]</code> to [contenthash]</code> in the output.filename</code> configuration in production.
Trying it again will now give the expected results: a change in our application code doesn't change the vendors</code> bundle.</p>
For many apps, just splitting the bundle that way will be enough to get started. If needed, you can create different kind
of strategies, for example:</p>

one file per npm</code> dependency</li>
group packages per update of frequency: put the ones that change often in the same bundle</li>
group packages per kind: all React packages could go in one bundle, all data viz in another etc</li>
have multiple entry points: Webpack will create one file per entry point</li>
</ul>
The Webpack documentation</a>
has some examples demonstrating how to implement some of the strategies. Once again, start with the default dumb splitting and experiment as you go when needed.</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/cd2669b62d9542794fdc52e6e6fb1702716ddc36</a>.</p>
Code splitting🔗</a></h3>
Code splitting is allowing you to import some code on demand. It relies on the dynamic import() proposal</a> which
is now on stage 4, eg finished. A simple React example would be:</p>
import </span>React </span>from </span>"react"</span>;
</span>
</span>class </span>LocationForm </span>extends </span>React</span>.</span>Component</span><{}> {
</span>   </span>handleClickOnMap </span>= </span>() </span>=> </span>{
</span>     </span>import</span>(</span>'./locationModal'</span>)
</span>      .</span>then</span>(({ </span>locationModal </span>}) </span>=> </span>{
</span>        </span>// Use locationModal
</span>      })
</span>      .</span>catch</span>(</span>err </span>=> </span>{
</span>        </span>// Handle failure
</span>      });
</span>   }
</span>
</span>   </span>render</span>() {
</span>     </span>return </span>(
</span>       </span><</span>form</span>>
</span>         <</span>button onClick</span>=</span>{</span>this</span>.</span>handleClickOnMap</span>}>Select location</</span>button</span>>
</span>       </</span>form</span>>
</span>     );
</span>   }
</span>}
</span></code></pre>
Imagine that the locationModal</code> component is loading Leaflet</a> and that this is the only place
where it is used. With the bundle splitting, Leaflet would be in your bundle even for users never seeing that form. If you are
doing code splitting, you will obviously need to make sure Leaflet is not part of another chunk. Another
obvious contender for code splitting is data visualisation: plottting libraries are typically heavy and if you only have them in one page you can split it from your bundle to
provide a faster experience for everyone.</p>
Code splitting is very powerful but not that useful if you are just starting: worry about it when your codebase is bigger. If you
are using React, the documentation page on code splitting</a> is very well written and should
answer most questions on how to actually use it.</p>
To use code splitting with TypeScript, you will also need to change module</code> in tsconfig.json</code> to esnext</code>.</p>
Analyzing bundles🔗</a></h3>
Once you have your bundle(s), a useful step is to actually check what they contain and whether there is fat that can be trimmed.
webpack-bundle-analyzer</a> is shining for that usecase.</p>
$</span> yarn add webpack-bundle-analyzer</span> --dev
</span></code></pre>
We only need to analyze bundles once in a while so I like to create a new script for it "analyze": "cross-env NODE_ENV=production ANALYZE=true webpack",</code> and
only instantiate the plugin when that ANALYZE</code> environment variable is set to true</code>.
Running analyze</code> will give you a treemap visualisation of each package used and their size, with and without gzip.</p>
Using this tool, it becomes very easy to notice some packages taking way more spaces than they should. The most classic examples I've seen
personally are not removing Momentjs</a> locales for an English only site and having the full Lodash</a> while
only using one or two functions.</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/41190ae6e279c84c8614d5d77656b8afaed1dea3</a>.</p>
Extracting CSS🔗</a></h2>
If you added Sass by following the previous article and looked at the bundle analyzer results, you might have noticed that the app bundle contains CSS. That's because
we've inlined them in our configuration via style-loader</code> and need to extract it to a separate CSS file in production environment instead using a plugin.</p>
$</span> yarn add mini-css-extract-plugin</span> --dev
</span></code></pre>
The change is pretty straightforward: we load the MiniCssExtractPlugin</code> loader instead of style-loader</code> in production and
add the plugin to the plugin list. The plugin can be set for every environment as it will not do anything unless the loader
is also used.</p>
Running build:prod</code> will now create a CSS file as well as a sourcemap in the dist</code> folder. I'm not 100% sure the sourcemap
is accurate as I have never used them for CSS.</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/e97a368d67e88f2c1adb9b018b8a4164fdfd3283</a>.</p>
Conclusion🔗</a></h2>
If you followed the articles or just cloned the repository, you should be in a good place to start actually building your project.
It might look complicated compared to create-react-app</a> but this is a minimal setup
that you understand and that only has things what you need. Well, being a JavaScript project it still pulls way too many dependencies just for that but
it's a good start.</p>


Setting up a React+TypeScript frontend with Webpack — Part 1
Unknown — Tue, 29 Oct 2019 00:00:00 +0000
Starting a new frontend project is tiresome. My usual process is to look at the last project I worked on,
try to extract all the base dependencies and configuration and see if a Hello World still works after upgrading everything.
This problem might be alleviated with tools such as create-react-app</a> but
I personally prefer not having an abstraction layer for the configuration as it is something I always end up having to
tweak. Even when using frameworks like Next.js</a> where the configuration is hidden, you still need
to make some changes and understanding Webpack</a> goes a long way in the frontend world.</p>
The article is split in two parts:</p>

Getting a local dev environment set up: this article</li>
Making it production ready: part 2</a></li>
</ol>
The focus for these article is to set up a build process for modern browsers with TypeScript: I am not going to pick any library other than React.
State management, testing framework etc are all up to you. The slight
exception to that rule is that I will use Sass</a> to handle the styling rather than alternatives such as Less/CSS-in-JS.
Once again, this is up to you. If you prefer to use JS for your CSS, just skip the last section of this article.</p>
I am also going to use yarn</a> as package manager but npm</code> will work as well.</p>
You can view the end result in https://github.com/Keats/webpack-react-typescript</a>.</p>
TypeScript setup🔗</a></h2>
TypeScript</a> is the most important tool for me in the frontend world. I first talked about
it on this blog in 2014</a> and it only got better with time. This is a superset of JavaScript, simply adding
types to it. I don't think static typing in dynamic languages are controversial anymore, seeing how many</a> languages</a> adopt it.
Static typing is the ultimate form of documentation as it HAS to be correct.</p>
Let's add it to the project:</p>
$</span> yarn add typescript</span> --dev
</span></code></pre>
This will create your project package.json</code> as well as a lock file: yarn.lock</code>.</p>
The next step is to create a tsconfig.json</code>, containing our TypeScript configuration:</p>
{
</span>  </span>"compilerOptions"</span>: {
</span>    </span>"module"</span>: </span>"es6"</span>,
</span>    </span>"moduleResolution"</span>: </span>"node"</span>,
</span>    </span>"esModuleInterop"</span>: </span>true</span>,
</span>    </span>"target"</span>: </span>"es6"</span>,
</span>    </span>"jsx"</span>: </span>"react"</span>,
</span>    </span>"sourceMap"</span>: </span>true</span>,
</span>    </span>"strict"</span>: </span>true</span>,
</span>    </span>"forceConsistentCasingInFileNames"</span>: </span>true</span>,
</span>    </span>"noUnusedLocals"</span>: </span>true</span>,
</span>    </span>"noUnusedParameters"</span>: </span>true</span>,
</span>    </span>"noImplicitReturns"</span>: </span>true</span>,
</span>    </span>"noFallthroughCasesInSwitch"</span>: </span>true</span>,
</span>    </span>"allowUnreachableCode"</span>: </span>false
</span>  },
</span>  </span>"include"</span>: [
</span>    </span>"./src/**/*"
</span>  ]
</span>}
</span></code></pre>
Let's go through them quickly:</p>

module</code> and esModuleInterop</code>: ensures we use the latest module system and compatible with the Babel ecosystem</li>
moduleResolution</code>: look into the node_modules</code> folder for packages</li>
target</code>: we target modern browsers so ES6 is fine here. If you need IE11 support, change it to es5</code></li>
jsx</code>: we use React and transpile from TypeScript directly so we use react</code></li>
sourceMap</code>: we want them</li>
strict</code>: enable all the strict flags automatically</li>
</ul>
All the other options are adding some additional checks, such as not allowing unused variables and a list
of all the options can be found in TypeScript documentation</a>.
Lastly, we set up an include path containing "./src/**/*"</code>: we will put all our code in a src</code> folder.</p>
In this setup, we will only use TypeScript and not Babel</a>. It is possible to use TypeScript for
typechecking only and pass the code to Babel for transpilation but, unless you need a specific Babel plugin, there are no
reasons to do that nowadays. You will have to wait a few more months before getting stage 3 features - not a big deal.</p>
The commit for that step can be seen in https://github.com/Keats/webpack-react-typescript/commit/a083ce1511b15c51d4a8d3ef95f2da05a669758b</a>.</p>
Webpack setup🔗</a></h2>
Let's start the slightly more complex part! Once you understand how Webpack works, this is actually pretty simple.</p>
Webpack itself🔗</a></h3>
We first need webpack and its CLI:</p>
$</span> yarn add webpack webpack-cli</span> --dev
</span></code></pre>
Let's also create a file named webpack.config.js</code> as well as a src</code> folder and an empty index.tsx</code> file in it.
Lastly, I always set up an .editorconfig</a> file to let text editors sync on how to format things.</p>
A very basic configuration for Webpack doing nothing would be something like:</p>
const </span>path </span>= </span>require</span>(</span>"path"</span>);
</span>
</span>module</span>.</span>exports </span>= </span>{
</span>    context: </span>__dirname</span>,
</span>    mode: </span>"development"</span>,
</span>    entry: {
</span>        app: </span>"./src/index.tsx"
</span>    },
</span>    output: {
</span>        path: </span>path</span>.</span>resolve</span>(</span>__dirname</span>, </span>"dist"</span>),
</span>        filename: </span>"app.[hash].js"
</span>    },
</span>    devtool: </span>"eval-source-map"</span>,
</span>    resolve: {
</span>        extensions: [</span>".js"</span>, </span>".jsx"</span>, </span>".ts"</span>, </span>".tsx"</span>]
</span>    },
</span>    module: {
</span>        rules: []
</span>    },
</span>};
</span></code></pre>
This means we are using src/index.tsx</code> as the entry point (e.g. what Webpack is loading) and the output will be created in
the dist</code> directory, containing the hash in the filename for caching reasons.
We use eval-source-map</code> as devtool</code> value as this is the best setting for development, You can see all the different values
in the Webpack devtool documentation</a>. Finally, we let Webpack know that
it should try to load imports with no extensions as .js</code>, .jsx</code>, .ts</code> and .tsx</code> (so we can do import something from "../index"</code>) and add a script to build our project.</p>
diff --git a/package.json b/package.json
</span>index eb50375..1bc2df7 100644
</span>--- a/package.json
</span>+++ b/package.json
</span>@@ -1,4 +1,8 @@
</span> {
</span>+  "scripts": {
</span>+    "build": "webpack",
</span>+  },
</span>   "devDependencies": {
</span>     "typescript": "^3.6.4",
</span>     "webpack": "^4.41.2",
</span></code></pre>
Running that script (yarn build</code>) will create the dist</code> folder containing a file with a name like app.5730f5cdf8cb70458282.js</code>.
Since we didn't write any code yet, it currently only contains Webpack's own code.</p>
The commit for those changes is in https://github.com/Keats/webpack-react-typescript/commit/48fc3f342c3f4f53c30af1b457d90351f442b4f0</a>.</p>
Loaders and plugin🔗</a></h3>
In this article we are aiming for a simple SPA without SSR so let's setup a super basic React application in order to actually bundle something.</p>
$</span> yarn add react react-dom
</span>$</span> yarn add @types/react @types/react-dom</span> --dev
</span></code></pre>
React doesn't ship the TypeScript type definitions by default so we need to download them manually.</p>
The simplest React code we can write in src/index.tsx</code> is:</p>
import </span>React </span>from </span>"react"</span>;
</span>import </span>ReactDOM </span>from </span>"react-dom"</span>;
</span>
</span>ReactDOM</span>.</span>render</span>(</span><</span>h1</span>>Hello world</</span>h1</span>></span>, </span>document</span>.</span>getElementById</span>(</span>"root"</span>));
</span></code></pre>
This will render the React app in the HTML element with id root</code>, which, as some of you might have noticed, doesn't exist yet.</p>
There is a plugin that will handle the HTML for us: html-webpack-plugin</a>.</p>
$</span> yarn add html-webpack-plugin</span> --dev
</span></code></pre>
We are using this plugin here because we do not need to display dynamic <meta></code> attributes depending on the page. If you
need it for SEO or other reasons, you will need to use another approach, likely involving some kind of SSR.</p>
Enabling it in our webpack.config.js</code> is trivial:</p>
diff --git a/webpack.config.js b/webpack.config.js
</span>index 2267dfd..bcbe494 100644
</span>--- a/webpack.config.js
</span>+++ b/webpack.config.js
</span>@@ -1,4 +1,5 @@
</span> const path = require("path");
</span>+const HtmlWebpackPlugin = require("html-webpack-plugin");
</span> 
</span> module.exports = {
</span>     context: __dirname,
</span>@@ -17,4 +18,7 @@ </span>module.exports = {
</span>     module: {
</span>         rules: []
</span>     },
</span>+    plugins: [
</span>+        new HtmlWebpackPlugin({ template: "index.html" }),
</span>+    ]
</span> };
</span></code></pre>
The template can be something very basic such as:</p>
<!</span>DOCTYPE </span>html</span>>
</span><html lang=</span>"en"</span>>
</span><head>
</span>    </span><meta charset=</span>"UTF-8"</span>>
</span>    </span><meta name=</span>"viewport" </span>content=</span>"width=device-width, initial-scale=1.0"</span>>
</span>    </span><meta http-equiv=</span>"X-UA-Compatible" </span>content=</span>"ie=edge"</span>>
</span>    </span><title></span>My project</span></title>
</span></head>
</span><body>
</span>    </span><div id=</span>"root"</span>></div>
</span></body>
</span></html>
</span></code></pre>
Do remember that the id</code> of a container needs to match the one set in index.tsx</code>.</p>
Trying to run the build against at this point will give you an error about a missing loader for this type of file, referring
to our index.tsx</code>.</p>
The commit for the above is https://github.com/Keats/webpack-react-typescript/commit/3af8820f98b3645381edfb99792700922823394b</a>.</p>
Loaders are the way Webpack knows what to do with each filetype. In our case, we have these TypeScript files but we didn't tell
Webpack what to do with them: we need to add a loader for it. In the case of TypeScript, we will add a plugin in addition.</p>
$</span> yarn add ts-loader fork-ts-checker-webpack-plugin</span> --dev
</span></code></pre>
The reason we use a loader and a plugin is performance: the loader will only perform transpilation while the plugin
will typecheck in another thread.</p>
diff --git a/webpack.config.js b/webpack.config.js
</span>index bcbe494..cd657ff 100644
</span>--- a/webpack.config.js
</span>+++ b/webpack.config.js
</span>@@ -1,5 +1,6 @@
</span> const path = require("path");
</span> const HtmlWebpackPlugin = require("html-webpack-plugin");
</span>+const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
</span> 
</span> module.exports = {
</span>     context: __dirname,
</span>@@ -16,9 +17,19 @@ </span>module.exports = {
</span>         extensions: [".js", ".jsx", ".ts", ".tsx"]
</span>     },
</span>     module: {
</span>-        rules: []
</span>+        rules: [
</span>+            {
</span>+                test: /\.(ts|tsx)$/,
</span>+                loader: "ts-loader",
</span>+                options: {
</span>+                    // We use ForkTsCheckerWebpackPlugin for typechecking
</span>+                    transpileOnly: true
</span>+                }
</span>+            },
</span>+        ]
</span>     },
</span>     plugins: [
</span>         new HtmlWebpackPlugin({ template: "index.html" }),
</span>+        new ForkTsCheckerWebpackPlugin(),
</span>     ]
</span> };
</span></code></pre>
Those changes are in the commit https://github.com/Keats/webpack-react-typescript/commit/a3fdbade49deaffd4b5cd762021920efad0fbc8c</a>.</p>
Running yarn build</code> again will now bundle our code: just open dist/index.html</code> to check for yourself. While opening that folder,
you might have noticed that there are many .js</code> files in there: we never actually cleaned that folder.
Nothing a Webpack plugin (clean-webpack-plugin</a>) or a rm -rf dist/</code> in the script cannot solve.</p>
The commit for the plugin way is https://github.com/Keats/webpack-react-typescript/commit/42ca8ba4f4ec0312d26defef610f7652a26ce40c</a>.</p>
webpack-dev-server🔗</a></h3>
We have our build working now but it builds from scratch every time, which sucks.
Thankfully, Webpack has some nice tooling with its dev server allowing Hot Modules Replacement (HMR): live reloading of your code
without having to refresh.</p>
$</span> yarn add webpack-dev-server</span> --dev
</span></code></pre>
And update webpack.config.js</code>:</p>
diff --git a/webpack.config.js b/webpack.config.js
</span>index 9bf647a..3b576bd 100644
</span>--- a/webpack.config.js
</span>+++ b/webpack.config.js
</span>@@ -1,4 +1,5 @@
</span> const path = require("path");
</span>+const webpack = require("webpack");
</span> const HtmlWebpackPlugin = require("html-webpack-plugin");
</span> const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
</span> const { CleanWebpackPlugin } = require("clean-webpack-plugin");
</span>@@ -29,9 +30,21 @@ </span>module.exports = {
</span>         },
</span>         ]
</span>     },
</span>+    devServer: {
</span>+        contentBase: path.join(__dirname, "dist"),
</span>+        port: 9000,
</span>+        hot: true,
</span>+        historyApiFallback: true,
</span>+        overlay: true,
</span>+        stats: "minimal"
</span>+    },
</span>     plugins: [
</span>         new HtmlWebpackPlugin({ template: "index.html" }),
</span>-        new ForkTsCheckerWebpackPlugin(),
</span>+        new ForkTsCheckerWebpackPlugin({
</span>+            // For the dev server overlay to work
</span>+            async: false,
</span>+        }),
</span>         new CleanWebpackPlugin(),
</span>+        new webpack.HotModuleReplacementPlugin(),
</span>     ]
</span> };
</span>
</span></code></pre>
And add a new script, dev</code> with a value of webpack-dev-server</code>. Running yarn dev</code> will now run a local server on
port 9000 that will also recompiles on change and reload the components without causing a refresh: try it for yourself
by changing the text index.tsx</code> while having the page open.</p>
Let's backtrack a bit to explain the devServer</code> options though. As always, the complete documentation is available
on Webpack documentation</a> but the key options there are:</p>

hot</code>: yes please, we do want HMR</li>
historyApiFallback</code>: if your app is a SPA with navigation you will need that option enabled to not see 404s</li>
overlay</code>: display errors as an overlay on the app, useful to ensure you're not missing it out from the terminal</li>
stats</code>: Webpack is very noisy by default, this turns the output level to something more reasonable</li>
</ul>
For the changes in the plugins</code> section, we do disable async</code> of ForkTsCheckerWebpackPlugin</code> to have overlay still
work as well as adding the builtin HMR plugin.</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/ed546d935487f4e4350e5267261b2c6a7bac015b</a>.</p>
At this point we have a functional working setup but there are a couple of tools we can add to improve the code quality.</p>
Auto-formatting🔗</a></h2>
Prettier</a> is a very nice tool to format pretty much every language used in the JavaScript world.</p>
$</span> yarn add prettier</span> --dev
</span></code></pre>
Prettier is opinionated and as such has few options</a> to configure. The only change I like to make is setting the maximum
number of characters in a line to be 100 instead of the default 80. It can be configured directly from package.json</code>.</p>
  </span>"prettier"</span>: {
</span>    </span>"printWidth"</span>: </span>100
</span>  },
</span></code></pre>
As well as a new script fmt</code>: prettier --write 'src/**/**.ts*'</code> that will format all TypeScript files in the src</code> folder.
The main issue is that for these tools to matter, they need to be enforced. An easy way to do that is via a commit hook, using
something like husky</a>. As with prettier</code>, we can configure husky</code> easily in package.json</code>:</p>
  </span>"husky"</span>: {
</span>    </span>"hooks"</span>: {
</span>      </span>"pre-commit"</span>: </span>"yarn fmt:check"
</span>    }
</span>  },
</span></code></pre>
where fmt:check</code> is a new script that only checks whether there are files needing to be formatted: prettier --list-different 'src/**/**.ts*'</code>.</p>
The next time someones working on that project calls git commit</code>, this command will be ran before and will fail if any file
needs formatting. Don't forget to run this command in your CI as well!</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/a464f58d80af0aa45be55bd3df87bb00d74ed958</a>.</p>
Linting🔗</a></h2>
The last code quality tooling we are going to add is ESLint</a>. Setting it up requires a few more
dependencies than the other tools as we need to make it work with React, Prettier and Typescript.</p>
$</span> yarn add eslint eslint-config-prettier eslint-plugin-react @typescript-eslint/eslint-plugin @typescript-eslint/parser</span> --dev
</span></code></pre>
The configuration is kept in a file named .estlintrc.js</code>:</p>
const </span>path </span>= </span>require</span>(</span>"path"</span>);
</span>
</span>module</span>.</span>exports </span>= </span>{
</span>  parser: </span>"@typescript-eslint/parser"</span>,
</span>  extends: [
</span>    </span>"plugin:react/recommended"</span>,
</span>    </span>"plugin:@typescript-eslint/recommended"</span>,
</span>    </span>"prettier/@typescript-eslint"
</span>  ],
</span>  parserOptions: {
</span>    project: </span>path</span>.</span>resolve</span>(</span>__dirname</span>, </span>"./tsconfig.json"</span>),
</span>    tsconfigRootDir: </span>__dirname</span>,
</span>    ecmaVersion: </span>2018</span>,
</span>    sourceType: </span>"module"
</span>  },
</span>  rules: {
</span>    </span>// Place to specify ESLint rules. Can be used to overwrite rules specified from the extended configs
</span>    </span>// e.g. "@typescript-eslint/explicit-function-return-type": "off",
</span>    </span>"react/prop-types"</span>: [</span>0</span>],
</span>  },
</span>  settings: {
</span>    react: {
</span>      version: </span>"detect" </span>// Tells eslint-plugin-react to automatically detect the version of React to use
</span>    }
</span>  }
</span>};
</span></code></pre>
Essentially we tell ESLint that we are going to use TypeScript and what configuration to use for the parser,
enable the recommended lints for React and TypeScript and lastly we add prettier/@typescript-eslint</code> to disable all rules
conflicting with prettier</code>. I also disable the react/prop-types</code> linting rule as we are using TypeScript and actually
have strongly typed props already.</p>
The linting script in our case is "lint": "eslint 'src/**/**.ts*'"</code>.</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/f30c07b1564457e55f9110c32ca766caf060b34d</a>.</p>
Bonus: Sass handling🔗</a></h2>
You can skip that section if you prefer using some CSS-in-JS.</p>
$</span> yarn add sass-loader node-sass style-loader css-loader</span> --dev
</span></code></pre>
As you might have understood already, we need to add some loaders</em> to handle Sass files in our Webpack config:</p>
{
</span>    </span>test</span>: </span>/</span>\.</span>s</span>[ac]</span>ss</span>$</span>/</span>i</span>,
</span>    </span>use</span>: [
</span>      </span>// Creates `style` nodes from JS strings injected in our index.html
</span>      </span>"style-loader"</span>,
</span>      </span>// Translates CSS into CommonJS
</span>      </span>"css-loader"</span>,
</span>      </span>// Compiles Sass to CSS
</span>      </span>"sass-loader"
</span>    ]
</span>}
</span></code></pre>
And then you need to tell Webpack to load the root file by importing it into your index.tsx</code> file, in my case
import "./style/app.scss";</code>. If you added scss</code> to resolve.extensions</code> in the Webpack configuration, you can skip the .scss</code>.
Live reload will continue to work with Sass editing: you can change the background colour and see it immediately reflected
in your browser.</p>
This setup will not solve the classic CSS specificity issues where some changes in a component might affect another component, unless
you are well disciplined with naming classes such as using BEM</a>. One nice automatic solution to that
are CSS modules</a> but that will likely be a separate article.</p>
Prettier also works with Sass so we can just add .scss</code> file to the format script and it will work automatically.</p>
The commit is https://github.com/Keats/webpack-react-typescript/commit/055c4785da3d167a18137a90c4ca887fddf7feed</a>, I've also
run Prettier manually on the configuration files to have consistent formatting throughout the project.</p>
What's next🔗</a></h2>
With that, we have a working development setup. It is not production and deployment ready however and that is what we will look at
in the second part</a>.</p>


Storing secrets in a git repository with git-crypt
Unknown — Sun, 18 Aug 2019 00:00:00 +0000
One of the most common issues working on a web service is where to store your secrets. When just starting, it's likely that
they will be directly in the repository itself whether it happens accidentally or not. Having your production secrets
in the clear in the repository is obviously a bad thing and all those secrets should be rotated.</p>
There are multiple ways to store your secrets securely:</p>

store them in the environment of the servers like Heroku/Aptible do</li>
store them as CI/CD variables like in Gitlab and bake them in Docker images</li>
use tools like Vault</a></li>
</ul>
If you are on a PaaS with an easy way to set secrets as environment variables, you can stop reading this article and just use that.</p>
However, if you're a small team using a more traditional deployment encrypting secrets in the repository itself is worth
considering. git-crypt</a> can be used for that. To quote the repository:</p>

git-crypt enables transparent encryption and decryption of files in a git repository.
Files which you choose to protect are encrypted when committed, and decrypted when checked out.</p>
</blockquote>
git-crypt</a> is available through many package managers.</p>
Once you have git-crypt</code> and are in your repository, run git-crypt init</code> to generate a key.</p>
The next step is to create a .gitattributes</code>, a file similar to .gitignore</code>, with the following content:</p>
secrets</span>/**</span>/* filter=git-crypt diff=git-crypt
</span></code></pre>
This means that everything inside a folder named secrets</code> will be encrypted. It is recommended to use the **/*</code> approach as
it would be easy to forget to encrypt some files otherwise.
Now that your .gitattributes</code> file is in place, you can start adding secrets in that folder. Since you have the secrets
already unlocked, you will see the file in your git diff</code> or git show</code>.
You can check which files are encrypted before pushing by running the git-crypt status -e</code> command:</p>
~/C/p/gitcrypttest</span> (master</span>|</span>…</span>) </span>[1]</span> $ git-crypt status</span> -e
</span>    </span>encrypted:</span> secrets/.envrc
</span></code></pre>
If you push it to a remote repository and try to view a file in that directory using the web browser for example, you will notice they are just binary data.
Anyone getting access to the repository will not be able to see them unless they can unlock git-crypt. That also includes you working from
a different computer or your team members.</p>
Clearly, we need to be able to unlock the secrets in more than one computer. There are two ways to go about it:</p>

GPG</li>
creating a symmetric key</li>
</ul>
You can read more about the GPG on the git-crypt's README</a>, I will use the symmetric
key for this article.</p>
Here's how you generate a symmetric key:</p>
$ git-crypt export-key /path/to/output/file
</span></code></pre>
This will generate a binary key that, after base64</code>'ing, can be stored in your password manager for example and shared securely
with team mates. And that's where the issue with this approach lies: some people might store the key insecurely which would be
equivalent to storing your secrets in the clear.</p>
For a small team that can be trusted however, this is an easy approach that can work for quite some time!</p>


Managing environment variables with direnv
Unknown — Thu, 30 May 2019 00:00:00 +0000
Following the Twelve-Factors app</a>, most web applications
are storing configuration in environment variables rather than in a repository. It is possible
to store secrets securely in a repository with git-crypt</a> but that will likely be the topic
of another article.</p>
While in CI and on servers loading those environment variables happen automatically, loading them on your computer is problematic. The
most popular approach is dotenv</code>: you store your environment variables in a .env</code> file and a library in your project will look for
it and load them. A .env</code> file sample:</p>
REDIS_URL</span>=</span>blabla
</span># Make sure this is not used in other environments
</span>APP_SECRET</span>=</span>hunter2
</span>TRIAL_DAYS_LENGTH</span>=</span>14
</span></code></pre>
And, for example in the JavaScript implementation, they can be loaded by adding require('dotenv').config()</code> to your project, as early as possible.
As you can see, this adds a dependency to your project that is only used in development: in CI variables are likely to be set in the CI itself and in production
by whatever provisioning tool you are using.</p>
Enter direnv</a>.</p>
It starts the same way as dotenv</code>: you write your variables in a .envrc</code> file which is almost identical to the example above: entries have an export</code> keyword first.</p>
export </span>REDIS_URL</span>=</span>blabla
</span># Make sure this is not used in other environments
</span>export </span>APP_SECRET</span>=</span>hunter2
</span>export </span>TRIAL_DAYS_LENGTH</span>=</span>14
</span></code></pre>
What sets it apart is how it loads the variables.
You first need to install direnv</code>, which is a cross-platform binary available on most package managers as well as set up a hook in your bash/zsh/fish config.
This might sound complex but you only need to do this setup once per computer and it actually takes less than a minute. The hook is fast enough that it
is imperceptible - no need to worry about terminal slowdown.</p>
Now that you have the direnv</code> hook, if you cd</code> to a directory with a .envrc</code> you will see:</p>
$</span> direnv: error .envrc is blocked. Run `</span>direnv</span> allow` to approve its content.
</span></code></pre>
As mentioned in the message, direnv</code> will not automatically load the variables found: you first need to allow the .envrc</code> file. You will need
to run direnv allow</code> every time the .envrc</code> is modified. Since direnv</code> loads the variable automatically, this is needed for security as any
repo could run commands on your machine otherwise.</p>
And that's it you're done. Every time you will cd</code> in a directory, it will automatically load variables found in .envrc</code> and unload them when moving
out of the directory:</p>
$</span> cd my-repo/
</span>direnv:</span> loading .envrc
</span>direnv:</span> export +AWS_ACCESS_KEY_ID +AWS_SECRET_ACCESS_KEY +RUST_LOG +SENTRY_DSN
</span>
</span>$</span> cd ..
</span>direnv:</span> unloading
</span></code></pre>
You get the benefits of environment variables for configuration without having to add a dependency to your project.
I was actually using direnv</code> before hearing about dotenv</code>: https://github.com/Keats/dbmigrate/pull/14</a> and I still don't really see myself using dotenv</code> over it.
I'm guessing the advantage of dotenv</code> is if you are launching things from an IDE directly, using Docker or at companies restricting what can be installed on a machine.</p>
If this is not your case, I highly recommend direnv</code>.</p>


Zola 0.6.0: start of multi-lingual sites
Unknown — Mon, 25 Mar 2019 00:00:00 +0000
Zola</a> is a powerful static site generator (SSG)
inspired by Hugo</a> but simpler to use. One of its goals is to try
to do as much as possible at built time: anchors, search, Sass, table of contents, syntax highlighting and more.
It is highly flexible and allows you to do any kind of sites:</p>

a blog like the one you are reading right now</li>
a landing page</li>
a knowledge base</li>
a gitbook: see the book theme</a></li>
a documentation site for your library like the one for Zola</a></li>
</ul>
You can find an up-to-date comparison of Zola with other SSG on the README</a>.</p>
What's new🔗</a></h2>
As usual, you can find the list of changes in the CHANGELOG</a> but we are going to have a look at the highlights in this post.</p>
Multi-lingual sites🔗</a></h3>
One of the most requested features is now starting to make its way in Zola!
As a recap, multi-lingual sites are sites available in multiple languages - surprising I know. In terms of Zola, this means
your content is written in multiple languages and that you can switch between them when possible. The approach taken is to have
the language code written in the filename: a blog-post.md</code> can have a blog-post.fr.md</code> for its French version.</p>
A more complete guide is available in the documentation</a>.</p>
Something to keep in mind is that this feature is likely to change in the future as more users use it and report their needs.
There are a few things missing:</p>

translations inside the templates, using something like fluent</a></li>
taxonomies are currently language specific, which doesn't really work if you want to have a taxonomy called
categories and have en-US</code> and en-GB</code> languages for example as it will conflict</li>
</ul>
Performance improvement🔗</a></h2>
In the 0.5.0 release post, I posted a screenshot of Zola building a test site.</p>

It is a blog with 10000 pages, paginated by 5 with several taxonomies (one of them having a RSS feed).
Each page contains shortcode, syntax highlighting and, although not used in the templates in this cases, a table of contents.</p>
</blockquote>
</p>
In 0.6.0, it is now a bit faster:</p>
</p>
The most important difference is that it is now using about 1/4 of the memory</strong> it used to use.</p>
Disabling syntax highlighting runs the same benchmark in about 5 seconds so there isn't too much overhead
on the Zola side.</p>
What's next🔗</a></h2>
Work is going to continue on the multi-lingual front based on the feedback received.</p>
Another thing will be a zola check</code> command to check that the site is in a good state without building it.
This will check all links (internal and external), duplicate pages, templates, Sass files and report any errors.
This is mostly built to replace the current external link checker which isn't very useable in its current state.</p>
I am also trying to move more features related issues to the forum</a> in order to keep the repository
issues be mostly bug reports.</p>
Lastly, I would also love more help on the documentation side as there were some reports the current structure is confusing.</p>


Gutenberg is out, Zola 0.5.0 is in
Unknown — Sat, 17 Nov 2018 00:00:00 +0000
Stop the presses! This is an important update for Gutenberg users - please read on
if you are one of them.</p>
Gutenberg/Zola</a> is a powerful static site generator (SSG)
inspired by Hugo</a> but simpler to use. One of its goals is to try
to do as much as possible at built time: anchors, search, Sass, table of contents, syntax highlighting and more.
It is highly flexible and allows you to do any kind of sites:</p>

a blog like the one you are reading right now</li>
a landing page</li>
a knowledge base</li>
a gitbook: see the book theme</a></li>
a documentation site for your library like the one for Zola</a></li>
</ul>
You can find an up-to-date comparison of Zola with other SSG on the README</a>.</p>
A bit of history and changing name to Zola🔗</a></h2>
The first commit on Gutenberg was done in May 2015 after the first stable version of Rust was released.
The goal for that project was for a friend and I to learn Rust and a SSG was a pretty good fit for that.
Since it was a learning project, we didn't really care about name conflict: we expected to be the only
users.</p>

If you are looking at the date of the first commit in the GitHub repo, you will see 2016.
When I started Gutenberg, there was no templates library I liked at the time so I spent some time
building Tera</a> and deleted the original repo as it was outdated by then.</p>
</blockquote>
Gutenberg grew more than anticipated and every time it got posted somewhere, half of the comments were pointing out
the name was not original. Most of the name conflicts were with Project Gutenberg</a> or
some CSS</a> frameworks</a>. I fully agree
with the people saying it isn't original. By that time, Gutenberg was already in many package managers and on Netlify</a>:
changing name was a bit problematic.</p>
More recently though, a small project called WordPress</a> started advertising their new editor, gutenberg</a>.
Being WordPress it will simply eclipse every single search for my Gutenberg and any others: I
already had trouble finding one of the CSS framework named Gutenberg while writing this post since all results were about the WordPress editor, which isn't
even released yet at that time.
Another point against the Gutenberg name is that my SO works for a WordPress agency: I hear about it all the time.</p>
I opened an issue</a> to rename the project and ended up choosing zola</code>.
Émile Zola is a very famous French writer - at least in France -, mainly for his J'accuse</a> letter. His
writing style doesn't appeal to everyone but his most famous books are L'Assomoir</a>
and Germinal</a> if you want to read one.
The name zola</code> itself it very short, easy to pronounce and I couldn't find any open-source projects with that name other than an inactive organization</a>.</p>
As the name is brand new, zola</code> will not be available immediately in all package managers and not natively on Netlify as I will talk about a bit more below.</p>
Changelog🔗</a></h2>
0.5.0 took longer than expected but is packed with bug fixes, new features and improvements. Part of the reason this
version has been so slow to be released is that I wanted to have Netlify support on release since all my sites
are using it. However, since my PR</a> to add it is not really being looked at, I decided
to stop waiting and release it now.
If you are using the current Gutenberg Netlify support, you can either stay on 0.4.1 or 0.4.2 or download the zola</code> binary manually like
mentioned in the documentation</a>.</p>
With that said, let's have a look at the headlines.</p>
Performance🔗</a></h3>
A big focus for this release was performance. While fast enough for medium sites (< 500 pages), it was slowing down
and consuming lots of memory when dealing with bigger sites and I knew some of the features
I wanted to add would make the problem even worse. Thanks to the help of @Freaky</a>, we were
able to improve speed dramatically (4-10x in general) while lowering the memory usage, you can see the evolution in the issue</a>.</p>
To give an idea of the speed, there are some benchmarks in the repository but you will need to generate them first: python gen.py</code> in components/site/benches</code>.
This will generate several sites of various sizes and setup but I'll use huge-blog</code> for illustration.
It is a blog with 10000 pages, paginated by 5 with several taxonomies (one of them having a RSS feed).
Each page contains shortcode, syntax highlighting and, although not used in the templates in this cases, a table of contents.
Here are the results on my 4.5 years old laptop:</p>
</p>
Not too bad. I am pretty sure we can optimize the speed further but I won't spend more time on it myself, I would rather
try to lower the memory usage right now, which is still way too high: I believe it used around 3GB during the screenshot above, which is insanely
high.</p>
Most of the time spent is now serializing the data to JSON for usage in Tera</a>.
There is an issue for writing Tera's own serde format</a> but I am not sure how it would look like
despite the help of @dtolnay</a>. If you have ideas on how to improve on that side, I am very happy to hear them!</p>
Ancestry🔗</a></h3>
Each page and section will now have all their parent sections paths in an ancestors</code> property.
This allows you to easily do breadcrumbs as well as just being able to access the parent section, which wasn't possible before.</p>
Loading CSV/TOML/JSON data🔗</a></h3>
A new Tera function aptly named load_data</code> has been added.
It can load data from both a local file or a remote URL and convert it to Tera values for usage in templates. As such, this is equivalent
to the feature some SSG call data files but also to getJSON</code> and getCSV</code> in Hugo. Thanks to serde</a>
for the super simple and powerful serializations!</p>
Date from filename🔗</a></h3>
If a page with a YYYY-MM-DD{-,_}</code> format, this date will now automatically be set as the page date, unless
overwritten in the front-matter, and the text after {-,_}</code> will be the slug.
For now, a slug is still required but it seems likely that I will allow a file named YYYY-MM-DD</code> in the future
as, in some cases like meeting minutes, pages do not always have a slug different from the date.</p>
Page templates🔗</a></h3>
Previously, if you had a site that was for example a landing page + blog, it is likely you would need
to specify the template to use to render a blog post on every page. A bit tedious and not very DRY.
From 0.5.0, you can set the page_template</code> attribute in a section and every pages below that section including subsections pages will use it.
Sub-sections can override it by setting their own page_template</code> and pages by setting template</code>.</p>
Transparent sections🔗</a></h3>
A commonly requested feature was the YYYY/MM/DD url scheme. I do not think it is a good
one and explained why</a> previously.
However, someone had a very good idea</a>: transparent section.</p>
By setting transparent</code> to true</code> in a section front-matter, all its pages will be passed to the parent section and so on,
until a section isn't transparent</code>.</p>
In practice, this allows you to do the YYYY/MM/DD scheme easily:</p>
.
</span>├──</span> 2018
</span>│</span>   ├── 10
</span>│</span>   │   ├── 10
</span>│</span>   │   │   ├── 2018-10-10_zola-release.md
</span>│</span>   │   │   └── _index.md
</span>│</span>   │   └── _index.md
</span>│</span>   └── _index.md
</span>└──</span> _index.md
</span></code></pre>
It is definitely more verbose than what Jekyll or Hugo (setting /:year/:month/:title/</code> in the config) but is also more powerful.
As far as I'm aware, you have no way of selecting the intermediate templates in alternatives or they are sometimes not rendered at all.</p>
For example, if I'm on https://intellij-rust.github.io/2018/11/07/changelog-86.html</a> and try
to want to see all the posts in 2018 (https://intellij-rust.github.io/2018/), I get a 404. I would be very surprised
if Jekyll doesn't handle that but it looks optional at least.</p>
Another advantage is that it isn't limited to the data in the front-matter: you can organise it however you want. Want to have a blog, prefix all the blog posts
by /blog/</code> but paginate it in the homepage? Create a blog</code> section, mark it as transparent</code>, paginate the index and you're done.</p>
Bug fixes🔗</a></h3>
Many bugs were fixed, including the big Tera one with macros that was shipped in 0.4.2.
Refer to the changelog</a> for a full list.</p>
Roadmap🔗</a></h2>
The first step now will be to get a Discourse</a> up and running to have a better forum than GitHub and move all discussions/feature requests to it in
order to keep the GitHub issues for actual bugs.
The major part of my effort will go towards Tera 1.0.0</a>, with a beta version shipping in a future version
of Zola soonish.</p>
I know I keep saying that on every release post but the focus for the next version will be on i18n support</a> since some
of the cleanup needed is now done. The RFC will need to be updated to take into account the new features in the last year once a Discourse instance is live.</p>
Lastly, if you are looking for a place to get started with Rust, Zola is great for that!
The codebase is relatively small and separated in a few sub-crates making it easy to contribute: you can modify the bit you want to change in the sub-crate,
compile/test only that one and once you're satisfied check where is the compiler complaining in the rest of the project. I will also help personally anyone wanting to start working on an issue.
This offer is valid for any of my projects</a> and if I don't respond for a while, don't hesitate to ping me.</p>


Atomic Design in Single Page Applications
Unknown — Fri, 26 Oct 2018 00:00:00 +0000
This post will outline how I architect visual part of the SPAs I work on. But first, let me explain the issues I faced that led me there.
I used to put every components in a components</code> folder, which obviously doesn't scale and make
it hard finding a specific component. After that, I grouped at least the top level routing
components which made things a bit tidier but was still very unsatisfying.
Looking around for various ways to organise design elements, I found Atomic Design</a>.
I am not going to dive deep into explaning what is Atomatic Design as the linked article does a very good job
so I would recommend taking 2 minutes to read it beforehand.</p>
You can find a basic clone of HackerNews</a> on GitHub: https://github.com/Keats/hn-react</a> made using
the principles described in this post to illustrate this article.</p>
Lastly, while the title doesn't mention a specific framework, all the samples will use React. The
ideas presented in this post will work equally well in Vue.js or any other component-based
framework.</p>
Self-contained components🔗</a></h2>
That is something Vue.js users can get behind!
Each component has now its own folder containing everything it needs to be used, apart from
the other components it is using as we will see in a bit.</p>
What this means is that every component folder looks very similar to something like:</p>
input
</span>├──</span> index.tsx
</span>└──</span> _style.scss
</span></code></pre>
You can replace tsx</code> by js</code> if you are not using TypeScript</a>.</p>
As you can see, the folder also contains a _style.scss</code>. I prefer to keep my CSS out of JS and since I use Sass</a>
for other projects without JavaScript, it makes sense to use it. You can use whatever floats your boat though.
Those Sass files are only targeting specific CSS classes of that component, which solves potentially overlapping styling:</p>
.input </span>{
</span>  // the CSS of the component
</span>}
</span></code></pre>
The main Sass file will import each component individual style after setting up some base rules like fonts or vertical rhythm as can be seen in
app.scss</a>.</p>
Since each component has its own folder, it is a good place to keep related code.
For example, if I am using GraphQL</a> with Apollo</a>, I will also have a queries.tsx</code> in there with the queries
used by the component as well as the types:</p>
import </span>gql </span>from </span>"graphql-tag"</span>;
</span>import </span>{</span>Query</span>} </span>from </span>"react-apollo"</span>;
</span>
</span>import </span>{</span>IOrganization</span>} </span>from </span>"../../../types"</span>;
</span>
</span>export </span>const </span>ALL_ORGS_QUERY </span>= </span>gql</span>`
</span>  query allOrgs {
</span>    organizations {
</span>      id
</span>      name
</span>      slug
</span>
</span>      members {
</span>        id
</span>        role
</span>
</span>        user {
</span>          id
</span>          name
</span>          timezone
</span>        }
</span>      }
</span>    }
</span>  }
</span>`</span>;
</span>
</span>export </span>interface </span>IData </span>{
</span>  </span>organizations</span>: </span>Array</span><</span>IOrganization</span>>;
</span>}
</span>
</span>export </span>class </span>AllOrgsQuery </span>extends </span>Query</span><</span>IData</span>> {}
</span></code></pre>
Now that we have seen how I organise each individual component, let's dive in the Atomic Design part.</p>
Atomic Design🔗</a></h2>
If you have read the article introducing Atomic Design, you can probably guess that your components</code> folder is going to look like that:</p>
.
</span>├──</span> atoms
</span>├──</span> molecules
</span>├──</span> organisms
</span>├──</span> templates
</span>└──</span> pages
</span></code></pre>
Let's look at them in the same order.</p>
Atoms🔗</a></h3>
Atoms are independent components that do not have any dependencies on other components and that exist in isolation: they
probably don't do anything on their own, are mostly composed of props</code> and any action they do is coming from props</code>.
In terms of Redux/MobX, all of those components should be dumb/pure/presentational components.</p>
Looking at one private project atoms, I have:</p>

button</code></li>
input</code></li>
link</code></li>
tag</code></li>
toast</code></li>
portal</code></li>
icon</code></li>
</ul>
There are obviously many more but this should be enough to give you an idea: they are the building blocks
of your site.</p>
Try to have as many of your components in that folder, you will have a much easier time composing interfaces later on.</p>
While atoms can become fairly complex (input</code> for example), they can also be as simple as a spinner</a>.</p>
Molecules🔗</a></h3>
By themselves, atoms are not very useful and need to be combined to make something useable: input</code> + button</code> giving you a form</code> for example.
That is what molecules are: a combination of 2 or more atoms</code> or, in rarer cases, a smart wrapper around an atom.
Therefore molecules should be dumb components when possible but it isn't required.</p>
Here are some of the molecules from the same project:</p>

form</code> (input</code> + label</code>): using MobX for state but dumb otherwise</li>
dialog</code> (overlay</code> + button</code>): dumb</li>
toast-container</code> (toast</code>): smart component that will display the currents <Toast></code> components from the store</li>
</ul>
Since the HackerNews repository is a basic example, I didn't create enough atoms to have interesting molecules. However, looking at
the story-item</a> it is easy to imagine
adding an upvote</code> atom in there.</p>
If you need to use a molecule in another molecule, it probably means it is an organism folder as we will now see.</p>
Organisms🔗</a></h3>
As with molecules, there are two types of organisms I distinguish here:</p>

components using one or more molecules</li>
business-specific usage of molecule</li>
</ul>
A good definition comes from the original article:</p>

Organisms are groups of molecules joined together to form a relatively complex, distinct section of an interface.</p>
</blockquote>
As before, here are some examples in my project:</p>

sidebar</code>: uses only one molecule but is a distinct section of the interface</li>
login-form</code>: the form</code> molecule set-up with the right fields and the GraphQL login query</li>
signup-form</code>: the form</code> molecule set-up with the right fields and the GraphQL signup query</li>
</ul>
Each form in the app gets its own component, making testing/storybook very easy.
Most of those forms components do not have style of their own as they just rely on the form</code> molecule for that.</p>
I do not have any organisms in the HackerNews example.</p>
Templates🔗</a></h3>
If you look at most SaaS sites, you will notice they use different layouts for different parts of their site:
the most common one being one logged out layout for the login/signup forms and the logged in layout
with your dashboard and the actual tool.</p>
I classify those different layouts as templates and you could have for example:</p>

logged-in</code>: a sidebar</code> organism on the left and the child</code> on the rest of the page</li>
logged-out</code>: a different background with centered forms</li>
settings</code>: some tabs</li>
</ul>
Each of those templates will have their own styling - since that's their main use - but potentially also queries: you probably
need to fetch the current user information for a logged-in</code> template so moving that query at the template level will allow each page using it
to automatically fetch the data in a uniform way.</p>
The HackerNews example has only one template</a> as, even
when logged in, the interface doesn't change significantly.</p>
Pages🔗</a></h3>
Those are the components you use in your router, each of them corresponding to a specific URL.
They are therefore connected to your data stores and will probably have to fetch some data from your server. Most of the time,
these components render</code> method will be wrapped into a template component to ensure consistent styling.</p>
Pages tie all of the elements of Atomic Design we just talked about in a small component. There shouldn't be any styling
in those components other than the (rare) occasional divergence.
I also follow a slightly more lax approach to the "one component = one folder" mantra and group sub-routes in the same folder as the main route
for easy discovery.</p>
Example of pages components:</p>

login</code></li>
home</code></li>
user-settings</code></li>
verify-email</code></li>
</ul>
You can view the HackerNews homepage</a> for an example.</p>
Conclusion🔗</a></h2>
While some of the rules I introduced seem inflexible, you can bend them so they make sense to you.
For example, I put my overlay</code> component in the atoms folder despite it using the portal</code> atom simply because I kept looking for it in the atoms folder
since I always forget it actually uses portal</code>.</p>
Overall, this structure has been a big improvement for me:</p>

super easy to find components (if you don't have a Go To Definition shortcut)</li>
trivial to test and make storybook stories</li>
self contained enough that I can copy-paste the atoms and molecules folder and have everything working quickly</li>
</ul>
As mentioned in the introduction, I wrote a HN clone</a> as an example for that article.
It is a basic React app following Atomic Design using TypeScript and MobX, as well as the routing
method I wrote about before</a> if you are curious about how it looks in practice.
In my own projects, I also use StoryBook</a> to easily have a visual overview of every component but I skipped adding it
for this example app.</p>


An overview of package management in Python in 2018
Unknown — Fri, 07 Sep 2018 00:00:00 +0000
First of all, this article will only talk about package management in the
context of backend applications. I do not maintain any Python library so I am
not able to give insights on that side of the package management story.</p>
I will begin by quickly explaining the most common way of setting up Python projects and handling dependencies
to make sure everyone is on the same page.</p>
A basic setup🔗</a></h2>
Pretty much all the Django/Flask projects I have seen use the same structure: a requirements</code>
folder containing several .txt</code> files listing the dependencies and their versions.</p>
The folder typically looks like the following:</p>
.
</span>├──</span> base.txt
</span>├──</span> local.txt
</span>└──</span> prod.txt
</span></code></pre>
base.txt</code> contains all the essential dependencies:</p>
boto3==1.6.10
</span>
</span>Django==2.0.3
</span>django-cors-headers==2.2.0
</span>django-filter==1.1.0
</span>django-floppyforms==1.7.0
</span>django-nested-inline==0.3.7
</span>django-storages==1.6.5
</span>djangorestframework==3.7.7
</span>djangorestframework-jsonp==1.0.2
</span>social-auth-app-django==2.1.0
</span>social-auth-core==1.7.0
</span>django-widget-tweaks==1.4.1
</span></code></pre>
While it is not required, every requirement files I have seen were using ==</code>, also called requirement pinning, to
depend on the exact versions to ensure reproducibility. Well, as much reproducibility
as a mutable package index allows anyway as we will see later.</p>
Other requirements files will import the base.txt</code> file and then add environment specific dependencies such
as testing libraries or developer tools for local.txt</code> for example.</p>
-r base.txt
</span>
</span>ipython==6.2.1
</span>flake8==3.5.0
</span>django-extensions==2.0.6
</span>mypy==0.570
</span>factory_boy==2.10.0
</span></code></pre>
But wait! Before being able to install the dependencies, you first need to create
a virtual environment</a> if you are not using Docker</a>. Python 3
has built-in support for virtualenvs and you can create one simply by running python3 -m venv tutorial-env</code>.
To activate it, you need to execute the activate</code> script in the bin</code> folder of the virtualenv.</p>
As this feature is somewhat recent, many virtualenv helpers exist to make it easier to use.
I use virtualenvwrapper</a> combined with the zsh</code> plugin with
the same name to automatically activate the right virtualenv when I'm cd</code>ing into a folder that has one.</p>
Now that your virtualenv is setup and activated, you can run pip install -r requirements/local.txt</code>
to install your dependencies.</p>
You can list the currently installed packages by running pip freeze</code> in the virtualenv. The downside is that it will also show
all indirect dependencies as well. You can order that list with the -r my_file.txt</code> argument to have your explicit dependencies
at the top but it isn't great.</p>
This process works but is quite manual:</p>

beginners might not know of virtualenvs and how to use them</li>
packages and their versions are edited manually so it is easy to make mistakes
by forgetting to add/remove one</li>
not really secure: the package index Pypi</a> is mutable so 2.1.0 one day
can be different from 2.1.0 another day and there will no way to know about it. While you can add
hashes to requirements files but I have never seen anyone go through the hassle of doing that themselves</li>
</ul>
We can see that when dealing with package management in Python there are two issues: dealing with virtualenvs
and actually managing the packages.</p>
There are plenty of tools that have been built to fix one or both issues; let's look at a few of them now.
I will use the list of packages of an actual Django project with about 28 dependencies to test them. While
speed is not THAT important for a package manager, I will only mention it if there is something to be said about it.</p>
pip-tools🔗</a></h2>
pip-tools</a> only tries to handle the package management part, meaning you still need to use
virtualenvwrapper</code> or something similar to handle virtualenvs.</p>
pip-tools</code> gives you two command line tools: pip-compile</code> and pip-sync</code>.</p>
The easiest way to get started with pip-tools</code> is to create a requirements.in</code> file listing your dependencies:</p>
boto3
</span>Django
</span>django-cors-headers
</span>django-filter
</span>django-floppyforms
</span>django-nested-inline
</span>django-storages
</span>djangorestframework
</span>djangorestframework-jsonp
</span>social-auth-app-django
</span>social-auth-core
</span>django-widget-tweaks
</span></code></pre>
The requirements.in</code> file uses the same requirements syntax as requirements.txt</code>:
I could indicate for example that I want Django==2.0.8</code> instead of the latest version.</p>
Running pip-compile</code> in the same folder will create a requirements.txt</code> file:</p>
#
</span># This file is autogenerated by pip-compile
</span># To update, run:
</span>#
</span>#    pip-compile --output-file requirements.txt requirements.in
</span>#
</span>boto3==1.8.7
</span>botocore==1.11.7          # via boto3, s3transfer
</span>certifi==2018.8.24        # via requests
</span>chardet==3.0.4            # via requests
</span>defusedxml==0.5.0         # via python3-openid, social-auth-core
</span>django-cors-headers==2.4.0
</span>django-filter==2.0.0
</span>django-floppyforms==1.7.0
</span>django-nested-inline==0.3.7
</span>django-storages==1.7
</span>django-widget-tweaks==1.4.2
</span>django==2.1.1
</span>
</span>... more lines
</span></code></pre>
pip-compile</code> automatically grabbed the latest versions and each line not present
in your requirements.in</code> has a comment indicating why it is here. This is already
a big improvement over pip freeze > requirements.txt</code>.</p>
Remember the packages hashes mentioned before? pip-compile --generate-hashes</code> can automatically computes the hashes and put them
in the generated file:</p>
#
</span># This file is autogenerated by pip-compile
</span># To update, run:
</span>#
</span>#    pip-compile --generate-hashes --output-file requirements.txt requirements.in
</span>#
</span>boto3==1.8.7 \
</span>    --hash=sha256:7b54cc29dde1d4833b082b8ef4062872297cf652ed20b2d485e1cae544c7cdad \
</span>    --hash=sha256:b181fb87661a4268174ba29cb5efbc9e728202f3f80e00356e8135ce50a3799b
</span>botocore==1.11.7 \
</span>    --hash=sha256:4d36cb3a0b6308eeb56f69b964b92b9f4609423b07a4979c298dba694a5a4bd6 \
</span>    --hash=sha256:86d0bf23b5071c6a956ad2a1d5cd8d1d7c997e2c04151f7c8fff50779a8315d8 \
</span>    # via boto3, s3transfer
</span>certifi==2018.8.24 \
</span>    --hash=sha256:376690d6f16d32f9d1fe8932551d80b23e9d393a8578c5633a2ed39a64861638 \
</span>    --hash=sha256:456048c7e371c089d0a77a5212fb37a2c2dce1e24146e3b7e0261736aaeaa22a \
</span>    # via requests
</span>chardet==3.0.4 \
</span>    --hash=sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae \
</span>    --hash=sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691 \
</span>    # via requests
</span>
</span>... more lines
</span></code></pre>
The initial run takes a bit of time but subsequent ones take under a second.</p>
The last thing we need for package management is an easy way to upgrade the packages and
pip-compile</code> provides that out of the box:</p>

pip-compile --upgrade</code> will update all packages</li>
pip-compile -P PACKAGE_NAME</code> will update only that package</li>
</ul>
An astute reader might have noticed that so far we have only managed to write and update
a text file and have not actually installed anything. That's where pip-sync</code> comes into play.</p>
Running pip-sync requirements.txt</code> will compare the packages listed in the file with
what is currently installed, installing the missing packages and uninstalling the packages
not listed. This ensures your virtualenv doesn't have extra dependencies and is representing
accurately your requirements file.</p>
The main con I have is pretty silly: why is it pip-compile</code> and pip-sync</code> instead of piptools compile</code>
and piptools sync</code>?</p>
Pipenv🔗</a></h2>
Pipenv</a> is developed by the Python Packaging Authority</a>,
responsible for developing pip</a> so I had big expectations.</p>
It is inspired by Cargo/Bundler/Yarn and introduces 2 files that you will recognize if you used any of them before:</p>

a Pipfile</code>: a TOML file listing packages as well as a minimal Python version</li>
a Pipfile.lock</code>: a lockfile in JSON format listing every dependencies version with their hash</li>
</ul>
Anytime you want to install the dependencies, Pipenv will read Pipfile.lock</code> and install everything in it.
To make it easier for users, Pipenv also wraps virtualenv, getting rid of the need to have virtualenvwrapper</code>. Pipenv seems
to be only targeting applications, it doesn't help if you are packaging a library.</p>
Let's see how it works in practice.</p>
The first step is to create a new project: pipenv --python 3.7</code>.
This is a pretty strange command as pipenv</code> only displays the help so I would have expected the command to be pipenv new</code>
rather than some flags. Typically flags in this situation are only there to display information, like pipenv --version</code>.
Pipenv will also create a new virtualenv when running pipenv install</code> if there isn't one.</p>
To activate the newly created virtualenv, run pipenv shell</code>. To exit it, simply type exit</code>.</p>
Running pipenv install django</code> will do two things:</p>

insert django = "*"</code> in the packages</code> table of the Pipfile</code></li>
download the latest django version, install it in the virtual env and add the hash/version in Pipfile.lock</code></li>
</ul>
Putting "*"</code> as a version number is not great: I need to read the Pipfile.lock</code> to see which version was installed
and *</code> is never a good default for a version number, even with a lockfile. Changing it to django = "==2.1.1"</code> which was
the version it installed did the trick.</p>
You can run pipenv sync</code> to do the equivalent of pip-sync</code> from pip-tools</code>, but using Pipfile.lock</code> as the truth this time.
Pipenv actually uses pip-tools</code> for some of its commands under the hood.</p>
A cool feature of Pipenv is pipenv check</code> that will check for security issues in your packages. Running a slightly
outdated version of Django for example gives the following:</p>
Checking</span> PEP 508 requirements...
</span>Passed!
</span>Checking</span> installed package safety...
</span>36368:</span> django </span>></span>=2.0.0, </span><</span>2</span>.0.8 resolved (2.0.5 installed)</span>!
</span>django.middleware.common.CommonMiddleware</span> in Django 1.11.x before 1.11.15 and 2.0.x before 2.0.8 has an Open Redirect. A remote user can redirect the target user</span>'s browser to an arbitrary site.
</span></code></pre>

PEP 508</a> is the grammar defining how to write dependencies versions, i.e. the ==</code> for example you
have seen before in that article.</p>
</blockquote>
Pipenv seems extremely slow: running pipenv install -d</code> the test project with already pinned versions took 166s.
Almost 3 minutes. Running it again right after took 55s. Any action dealing with packages
takes a minimum of 30s on my machine. I did say in the introduction that speed is not too important but Pipenv does test the limit
of that affirmation.</p>
Lastly, I found the UX of the whole tool to be pretty awkward or buggy:</p>

pipenv</code> shows an help menu with the various actions but pipenv check --help</code> for example will not tell you
what pipenv check</code> actually does, only what flags are available</li>
pipenv uninstall</code> is said to "Un-installs a provided package and removes it from Pipfile." but somehow pipenv uninstall --three </code>
will destroy the current virtualenv and create a new one? It looks like all subcommands have the same flags available to
create/recreate a virtualenv instead of having a pipenv new</code> command and avoid this pitfall.</li>
errors are very cryptic: I made a typo while adding a dependency in Pipfile</code> resulting in an invalid TOML variable and all I got was
two tracebacks for a total of 70 lines with the reason on the last line. How about only showing me the reason instead?</li>
pipenv update</code> doesn't tell what was actually updated...?</li>
pipenv update django</code> updates all the packages instead of only django....?</li>
</ul>
poetry🔗</a></h2>
I believe I first heard of poetry</a> while looking up Black</a> and noticing
a pyproject.toml</code>.</p>
PEP 518</a> introduced pyproject.toml</code>:</p>

This PEP specifies how Python software packages should specify what build dependencies they have in order
to execute their chosen build system.
As part of this specification, a new configuration file is introduced for software packages to use to specify
their build dependencies (with the expectation that the same configuration file will be used for future configuration details).</p>
</blockquote>
The interesting part of that PEP for the purpose of this article is the tool section</a>.</p>
Rather than having one config file for each tool like Flake8</a> or Black, having
all of them consolidated in one file would be very valuable.</p>
Poetry uses this file to list the dependencies, keeping everything neatly in place.</p>
There are two ways to get started with poetry:</p>

poetry new SOME_NAME</code>: will create a folder named SOME_NAME with some basic structure setup for a Python project</li>
poetry init</code>: an interactive way to setup your project and some dependencies</li>
</ul>
The downside of the poetry init</code> is that the package search is not that great: searching for django</code> will
return a list of 99 packages, all of them being django-something</code> and not the actual django. I don't know what Pypi
offers as an API so maybe it is a limitation of the API but even then, showing 99 results is not very user friendly and
if there is an exact match it should show it to you.
The help text says I can enter the exact package name but typing django</code> tries to autocomplete with the package names
from the list and results in an error:</p>
 </span>></span> django
</span>Value </span>"django"</span> is invalid
</span>
</span>Enter</span> package </span># to add, or the complete package name if it is not listed:
</span> </span>[</span> 0] django-bagou
</span> </span>[</span> 1] django-maro
</span> </span>...</span> 99 packages
</span></code></pre>
Poetry will also create virtualenv automatically when running install</code>, add</code> or remove</code> with the current version of python</code>:
you cannot currently create a virtualenv with a different version.</p>
You are supposed to activate a shell with poetry shell</code> but it breaks if you using $WORKON_HOME</code> for other tools:
https://github.com/sdispater/poetry/issues/214 so I ended up ignoring the virtualenv related commands. I didn't spend time looking
into it so there might be an easy fix but it should work out of the box with the rest of the ecosystem.</p>
If you try to install a package using poetry add django</code>, you will notice that a pyproject.lock</code> has been created
and that some dependencies were added to pyproject.toml</code>:</p>
[</span>tool.poetry.dependencies</span>]
</span>python </span>= </span>"3.7"
</span>django </span>= </span>"^2.1"
</span>
</span>[</span>tool.poetry.dev-dependencies</span>]
</span>pytest </span>= </span>"^3.0"
</span></code></pre>
As opposed to the other tools, poetry</code> uses the semantic versioning to refer to dependencies versions. If you have used
Cargo</a> in Rust, you will feel at home. The issue is that many Python libraries do not use
semantic versioning so it does feel a bit weird to use in this context.</p>
While trying to clean its cache to test the speed, I ran into a small UX issue.
Poetry offers a command to clean the cache (poetry cache:clear</code>) but it takes a path/string to a cache as an argument. A new
user like me will not know what argument to give, especially since the command is not in the documentation</a>.
Looking into issues, we can see that we can run poetry cache:clear --all pypi</code> but the documentation doesn't even mention cache:clear</code> so it's not
obvious.</p>
As expected, the initial poetry install</code> takes some time but subsequent runs take under a second.
The UI is very clean and clear about what was installed and their versions.</p>
Poetry also has poetry update</code> to update dependencies and once again makes it clear what has changed.</p>
While this post is focused on backend applications, it is worth mentioning that Poetry apparently handles building and publishing
libraries as well which is a big plus if you are a maintainer: one tool for all purposes!</p>
My opinion🔗</a></h2>
I have only mentioned 3 tools but there are way more! I wouldn't be surprised if Python had the highest
number of tools dedicated to package and environment management of any programming language.
Since all those tools are written in Python themselves you still need to use Pip first to install them, globally sometimes. A better solution
in my opinion would be to write the package manager in a language compiling down to a binary, solving the bootstrapping issue and
being a good example of https://xkcd.com/927/</a>.</p>
To go back to the three tools mentioned in this article, I would recommend either pip-tools or poetry.
My limited usage of Pipenv had too many WTFs to be considered ready for actual use, not even taking into account
its extreme slowness. I'm not entirely sure why it is the recommended tool other than the virtualenv setup was easy to do because it feels
like an alpha version. If you are using Docker containers instead of virtualenvs, I don't see any advantage of Pipenv over pip-tools or Poetry.</p>
I like the simplicity of pip-tools</code>. If you are currently writing requirements.txt</code> by hand, using pip-tools</code> to get
some extra features like hashes is a pretty small step to take which I would recommend right now.</p>
On the other hand, if pyproject.toml</code> gets adopted by other tools (Flake8, mypy etc), having everything in one file would be very
appealing and poetry would become the best choice at that time. I expect poetry</code> to work with my current use of virtualenvwrapper</code> though,
I don't want to convert all my projects to poetry</code> just to make it happy.</p>


Gutenberg 0.4.0: custom taxonomies, image processing and more
Unknown — Sat, 04 Aug 2018 00:00:00 +0000
Gutenberg</a> is a powerful static site engine inspired by Hugo</a> but simpler to use.
You can build pretty much any kind of static site with it using markdown:</p>

a basic blog</li>
a landing site</li>
a knowledge base</li>
a gitbook (there is a theme</a> for that)</li>
a documentation site</li>
all of the above combined</li>
</ul>
You can download built binaries from the Github releases page</a> or install
it from one of the installation methods</a>.</p>
You should also be able to install it on Ubuntu via Snapcraft once this bug</a>
is resolved.</p>
What's new🔗</a></h2>
Lots of things! You can view the CHANGELOG</a> for
a quick overview: I will look at the biggest changes in more details here including the breaking ones and how to migrate.</p>
Breaking: custom taxonomies🔗</a></h3>
Taxonomies are a way to group content together, the most common one in blogs being tags and categories.
Before 0.4.0, you could only have those two taxonomies: tags</code> and categories</code>. You
couldn't paginate their pages, have a RSS feed for each or create your own taxonomy.</p>
Let's see how to use, and also how to migrate from the point of view of a current user
already using tags/categories.</p>
If you are looking for more information, the docs</a> have been updated — look
for the various taxonomies pages in the side menu.</p>
Updating the configuration🔗</a></h4>
The first thing to do is open your config.toml</code> and list the taxonomies you want to use:</p>
# You can delete those 2 lines, they aren't used anymore.
</span>generate_tags_pages </span>= </span>true
</span>generate_categories_pages </span>= </span>true
</span>
</span># And define them like so instead
</span>taxonomies </span>= [
</span>    </span># each tag will have its own RSS feed
</span>    {</span>name </span>= </span>"tags"</span>, </span>rss </span>= </span>true</span>},
</span>    </span># 5 items per page for a term, you can also customise the pagination path
</span>    </span># like for the rest of the paginated content
</span>    {</span>name </span>= </span>"categories"</span>, </span>paginate_by </span>= </span>5</span>},
</span>    </span># Basic definition: no RSS or pagination
</span>    {</span>name </span>= </span>"authors"</span>},
</span>]
</span></code></pre>
Updating the templates🔗</a></h4>
We need to change two things regarding the taxonomies templates:</p>

their location</li>
the main variable they use</li>
</ul>
First we need to move the templates their new location:</p>

tags.html</code> -> tags/list.html</code></li>
tag.html</code> -> tags/single.html</code></li>
categories.html</code> -> categories/list.html</code></li>
category.html</code> -> categories/single.html</code></li>
</ul>
In short, Gutenberg is now looking for:</p>

$TAXONOMY_NAME/single.html</code></li>
$TAXONOMY_NAME/list.html</code></li>
</ul>
Lastly, the name of the variables available have changed:</p>

replace tags</code> and categories</code> with terms</code></li>
replace tag</code> and category</code> with term</code></li>
</ul>
Updating the content🔗</a></h4>
Before, your front-matter would look like:</p>
+++
</span>title = "Provisioning and deploying this blog with Ansible"
</span>description = "Showing off Ansible by example"
</span>date = 2013-08-17
</span>category = "Devops"
</span>tags = ["ansible"]
</span>+++
</span></code></pre>
An updated version is:</p>
+++
</span>title = "Provisioning and deploying this blog with Ansible"
</span>description = "Showing off Ansible by example"
</span>date = 2013-08-17
</span>
</span>[taxonomies]
</span>categories = ["Devops"]
</span>tags = ["ansible"]
</span>+++
</span></code></pre>
Note that every taxonomies is now required to take an array of string, whereas before
there could be only a single category.</p>
Breaking: removal of order</code> sorting & renaming of next</code>/previous</code>🔗</a></h3>
Before 0.4.0, you could sort pages by date</code>, order</code> and weight</code>.</p>
order</code> and weight</code> were the opposite of each other but the difference of meaning led
to confusion</a> when trying to get the previous</code> or the next</code> page.</p>
To make things more explicit two changes have been made:</p>

order</code> has been removed</li>
page.previous</code> and page.next</code> have been renamed depending on the sorting used:

date</code>: now called page.earlier</code> and page.later</code></li>
weight</code>: now called page.lighter</code> and page.heavier</code></li>
</ul>
</li>
</ul>
No more <a class="previous" href="{{page.next.permalink}}>{{page.next.title}}</a></code>!</p>
To fix sites using order</code> or date</code>, you will need to:</p>

change sort_by</code> of the sections to use weight</code></li>
rename order</code> to weight</code> and invert the order of values if necessary</li>
rename next</code> and previous</code> to heavier</code>/lighter</code> or later</code>/earlier</code></li>
</ul>
This has been implemented by Daniel Sockwell</a> as his first ever Rust PR!
Daniel has also made tons of improvements to the documentation, something always appreciated.</p>
Image processing🔗</a></h3>
This is the amazing work of Vojtech Kral</a> who also wrote
a thorough documentation page</a> explaining it in detail.</p>
In short: you can now resize images from a template and implementing a gallery is trivial. Open an issue if you have an idea for
some image processing not already in!</p>
Shortcodes fixes🔗</a></h3>
In the previous versions, shortcodes</a> were detected with a Regex and built up
while parsing the Markdown which ended up being some of the worst spaghetti code I have ever written.
It lead to numerous bugs as well some valuable features like array arguments to be almost impossible to implement — at least for me.</p>
In Gutenberg 0.4.0, shortcodes are now rendered before Markdown as a separate pass, going through a custom parser specifically written for it.
The rendered shortcodes are then inserted back into the Markdown as raw HTML so the (much simplified) Markdown parser can ignore them.
Thanks to that redesign, all shortcodes feature requests were added easily and every known bug has been fixed.</p>
External link checker🔗</a></h3>
Link rot can be a big issue: some pages might not make sense anymore as a whole if an important link stopped working.</p>
Since Gutenberg already checks internal links, only external links were left to check!
Simply add check_external_links = true</code> to your config.toml</code> and Gutenberg will look up every link in your pages, reporting the ones
not working.</p>
This process is quite slow though so I would recommend enabling it once in a while to check but not all the time.
Keep in mind that some results might be false negatives: crates.io for example always returns a 404</a>.</p>
What's next🔗</a></h2>
The main goal for the next version is i18n support. There is an open RFC</a> to
discuss how the implementation would look like, comments are very welcome.</p>
The main issue left seems to be the translation of the template texts as I'm not sure how to handle that.
Right now it's a dictionary in config.toml</code> but that can grow to be quite large so a separate file for each language
would make sense. Pluralization also becomes an issue.</p>
Once the spec is clearly defined on all points, I would happy to mentor people of any skill level on bits of it: gutenberg</code> is divided in
many sub-crates, making changes pretty self-contained.</p>
As always if you have any feedback or bugs, please open an issue. Hopefully soon Gutenberg will have enough users
to qualify for a free open-source Discourse forum to have a good way to interact with users more efficiently than GitHub issues.
If you are using Gutenberg and are not featured in the list of sites</a>, please
add yourself!</p>


Tera 0.11 is released
Unknown — Mon, 22 Jan 2018 00:00:00 +0000
The work on this version started in September 2017 so I'm pretty happy to finally have this published.</p>
The changelog</a> is pretty thorough but the main
highlights are:</p>

whitespace handling</li>
default arguments for macros</li>
tests, global functions calls and macro calls are now expressions and can be combined like so: if x is divisibleby(2) and x > 10</code></li>
</ul>
Quite a few of the changelog items were written by contributors and I hope this trend continues: thanks
to @upsuper</a>, @Alex-PK</a>, @jturner314</a>,
@hoggetaylor</a> and @alex</a> for that.</p>
What's next🔗</a></h2>
I am satisfied with the current feature set of Tera and am not planning to do significant changes
to the template language itself, which brings us to a 1.0!</p>
I expect most of the changes until then to happen to the Rust side:</p>

ergonomics improvement: I'm pretty happy with it so would welcome other viewpoints</li>
template rendering performance improvement (reducing the number clone()</code>, etc)</li>
look into the benefits of failure</a>
and whether it's worth moving from error-chain</a> (no at a first glance)</li>
try to get something like streamable templates</a> in or wait if it would be nicer when generators are stable</li>
look into https://github.com/Keats/tera/issues/219</a></li>
</ul>
If you think you can help with any of the points above, please leave a comment on the associated issue or create a new one.</p>


Gutenberg 0.1.3: themes are in
Unknown — Thu, 31 Aug 2017 00:00:00 +0000
Gutenberg</a> is a powerful static site engine inspired by Hugo</a> but simpler to use.
You can build pretty much any kind of static site with it using markdown:</p>

a basic blog</li>
a landing site</li>
a knowledge base</li>
a gitbook</li>
a documentation site</li>
all of the above combined</li>
</ul>
You can download built binaries from the Github releases page</a>.</p>
What's new🔗</a></h2>
The highlight of this release is, as you might have guessed from the title of the post, themes.</p>
Themes are a staple of static site engines: you can use one to get started with your site and only tweak little bits.</p>
As a proof of concept I have ported a famous theme from Jekyll: hyde</a>.</p>
Since Tera</a>, the template engine used in Gutenberg,
supports multiple levels of inheritance</a>, using a theme is almost seamless.
For example, if you want to change the about part of the sidebar of Hyde, it is as easy as adding a index.html</code> in your
templates</code> folder with the following:</p>
{% </span>extends </span>"hyde/templates/index.html" </span>%}
</span>
</span>{% </span>block </span>sidebar_about </span>%}
</span>    Something else
</span>    You can of course render the theme block
</span>    first by calling </span>{{ </span>super</span>() </span>}}</span> if wanted.
</span>{% </span>endblock </span>sidebar_about </span>%}
</span></code></pre>
The architecture chosen for themes is the same as Hugo</a>: you have a themes folder in which you download your
themes (via git clone</code> or copy/paste) and tell Gutenberg which one to load by adding a theme = "theme_name"</code> line in your config.toml</code>.</p>
This is the first pass at themes so there are probably features missing or bugs laying around but it's ready to be used!</p>
What's next🔗</a></h2>
The main focus now will be to get a site up and running for Gutenberg and to put it in various package managers.
If someone reading this is on Mac and has some time to spare, I would love to get it on Homebrew but I don't have access to one.</p>
Lastly, the i18n RFC</a> is open. If you are interested
in multi-lingual sites, please have a look and comment!</p>


Releasing Gutenberg 0.1.0
Unknown — Fri, 14 Jul 2017 00:00:00 +0000
Gutenberg</a> is a powerful static site engine inspired by Hugo</a> but simpler to use.
You can build pretty much any kind of static site with it using markdown:</p>

a basic blog</li>
a landing site</li>
a knowledge base</li>
a gitbook</li>
a documentation site</li>
all of the above combined</li>
</ul>
You can download built binaries from the Github releases page</a>. If you were using Gutenberg
through Cargo, I will not upload new versions to crates.io for three reasons:</p>

package for binary crates don't use the Cargo.lock</a> which means a dependency having breaking changes
without respecting SemVer will cause the crate to compile but fail at runtime</a> in some cases</li>
I moved to using a Cargo workspace with many small crates to improve iteration speed</li>
with Sass, building Gutenberg has become more involved and it is easier to let user install the already built binary</li>
</ul>
As mentioned in my article introducing Gutenberg</a>,
my main issue with Hugo is the extremely poor — and I'm being kind here — template engine it is using.
This was solved in the first release of Gutenberg by using a template engine similar to Jinja2 I wrote: Tera</a>.</p>
Another annoying thing was that, since I was using Sass</a> to write CSS, each static site had to set up
Sass compilation, usually with node/yarn/gulp.</p>
With Gutenberg 0.1.0, this is solved as it ships with a static version of libsass, the C++ Sass compiler and allows
commits like this one</a>.</p>
Let's have a look at the current set of features - it's pretty packed for a 0.1.0:</p>

live reload</strong>: when anything changes, Gutenberg will do the minimum work required and will live reload assets (js/css/images/...) if possible</li>
syntax highlighting</strong> built-in via syntect</a></li>
pagination</strong></li>
easy internal linking</strong>: they look like [my article](@/blog/blabla.md)</code></li>
automatic table of contents</strong></li>
automatic insertion of anchors on titles</strong>: same as READMEs on Github</a></li>
shortcodes</strong>: when you want to insert some HTML in a page but don't want to copy the HTML everywhere. For example
{{ youtube(id="dQw4w9WgXcQ") }}</code> is a built-in shortcode and will insert the YouTube video for that id.</li>
Sass compilation</strong></li>
RSS feed</strong> generation when requested</li>
Tags and categories</strong> generation when requested</li>
co-location of assets and content</strong>: when an article has some images and you want to keep them in the same folder</li>
</ul>
What's next🔗</a></h2>
The current features are pretty much what I wanted to have when I started Gutenberg but that doesn't mean there isn't anything left to do!</p>
i18n🔗</a></h3>
The discussion started on github</a> but as it isn't a feature I need, I would
rather have someone else doing it, once there is consensus on the implementation</p>
Alternative rendering backends🔗</a></h3>
Right now, only markdown is supported. While I definitely don't want to have too many backend, Asciidoc</a>
is one I was interested in and antoyo</a> started working on a asciidoc implementation so
it should be coming eventually!</p>
Theme support🔗</a></h3>
An issue</a> was opened on Gutenberg to support themes.
While the idea in the issue is IMO too complex, I would like to have some theme support baked in gutenberg</code>,
unless the git clone a-template-repo</code> approach is simpler.</p>
Deploying🔗</a></h3>
A subcommand to upload/push the generated site to Github Pages/server/service could be nice. Maybe this can be resolved
with documentation instead though.</p>
A documentation site🔗</a></h3>
Now that things are a bit more stable in Gutenberg, I will start working on a documentation site as Gutenberg Readme is currently not
nearly enough. I've already started one for Tera</a> and am mostly waiting for design inspiration
before publishing it.</p>
Packaging🔗</a></h3>
Lastly, I think it's time to put Gutenberg in packages managers</a>. I will probably
put it on AUR</a> if no one beats me to it but I will need help for the other package managers.</p>
Conclusion🔗</a></h2>
As always I welcome any feedback. If you are using Gutenberg, please reply on this issue</a> so I
can update the list in the README.</p>
Joyeux 14 Juillet!</p>


A different approach to routing in Single-Page Applications: now in production
Unknown — Wed, 24 May 2017 00:00:00 +0000
I've recently wrote an article</a> about a
framework agnostic routing approach for SPA and promised to post an update once it is a bit more tested.
I have since moved Proppy from react-router</a> v2 to
the structure described in my article and the result is pretty great!</p>
I did change a few things from it though.</p>
First, the onClick</code> of the Link</code> component was incorrect and has been changed to:</p>
private </span>onClick</span>(</span>event</span>: </span>React</span>.</span>MouseEvent</span><</span>{}</span>></span>) {
</span>    </span>event</span>.</span>preventDefault</span>();
</span>    </span>event</span>.</span>stopPropagation</span>();
</span>    </span>// I also changed the props `name` to `to`
</span>    </span>const </span>{</span>to</span>, </span>params</span>, </span>options</span>} </span>= </span>this</span>.</span>props</span>;
</span>    </span>router</span>.</span>navigate</span>(</span>to</span>, </span>params</span>, </span>options</span>);
</span>}
</span></code></pre>
The store also changed in order to only display an animation after a certain amount of time, avoiding blinking effects:</p>
class </span>RouterStore </span>{
</span>  @</span>observable current</span>: </span>State</span>;
</span>  @</span>observable asyncInProgress </span>= </span>false</span>;
</span>  </span>// Only happens if the page wasn't loaded in less than 500ms
</span>  @</span>observable showLoadingScreen </span>= </span>false</span>;
</span>  </span>loadingTimeout</span>: </span>null </span>| </span>number</span>;
</span>
</span>  @</span>action </span>setCurrent</span>(</span>state</span>: </span>State</span>) {
</span>    </span>this</span>.</span>current </span>= </span>state</span>;
</span>    </span>this</span>.</span>asyncInProgress </span>= </span>false</span>;
</span>    </span>clearTimeout</span>(</span>this</span>.</span>loadingTimeout</span>);
</span>    </span>this</span>.</span>showLoadingScreen </span>= </span>false</span>;
</span>  }
</span>
</span>  @</span>action </span>startAsyncLoading</span>() {
</span>    </span>this</span>.</span>asyncInProgress </span>= </span>true</span>;
</span>    </span>this</span>.</span>loadingTimeout </span>= </span>setTimeout</span>(() </span>=> </span>this</span>.</span>showLoadingScreen </span>= </span>true</span>, </span>500</span>);
</span>  }
</span>}
</span></code></pre>
Any component can now observe showLoadingScreen</code> and render a loading effect very easily. 500 milliseconds is probably
too high but I was on a slow connection several thousands of kilometers away from our servers when I tried it.</p>
The only issue we encountered was that some users were faced with a blank page. I was not able
to reproduce it and no errors were reported to our Sentry server. After a couple of unsuccessful debugging
sessions, I noticed something in the router5 documentation</a>:
the strictQueryParams</code>.</p>
By default in router5</code>, a route with a path of /</code> will not be matched by the URL /?_ga=blabla</code>:
turns out this was exactly what was happening for Proppy. I
opened an issue</a> to change the default to a saner one and it seems
it will happen, but in the next major version as this is a breaking change. In the meantime,
the paragraph about strictQueryParams</code> got moved to the top in the docs in order to be more visible.</p>
Lastly, someone mailed me mentioning react-mobx-router5</a> which
was inspired by the same article</a>
as this serie of posts. I think a library for this routing approach is overkill. Pretty much all the code needed is in
the previous article</a> and is less than 100 LOC that you can customise
any way you want since different apps will have different needs.</p>


A different approach to routing in Single-Page Applications
Unknown — Mon, 08 May 2017 00:00:00 +0000
Routing is a big part of most SPA:</p>

what to render when a user hits a certain URL</li>
whether the user is allowed to reach that page</li>
what data do we need to load before rendering</li>
eventually display some loading screen if necessary.</li>
</ul>
The problem🔗</a></h2>
In the React world, React-Router</a> is the standard.
It is a bit infamous as its API has changed drastically for each major version.
Proppy is still using v2 as updating it didn't seem to bring much benefit and would take time.
Our only issue with our current setup is that we are not able to make the async transitions the way we would like them to be, but it is
an annoying one from a UX point of view.</p>
After reading How to decouple state and UI (a.k.a. you don’t need componentWillMount)</a> by the author of MobX</a>, I realised that routing should be something that is framework-agnostic.
After all, isn't routing simply matching a URL state to a function? There is no need for something specific to React, Angular or anything else.</p>
I recently started experimenting with it and I think I found a nice setup.
I haven't tried it for a complex app yet though so it is probably lacking in some ways.
I will write another article on how it works in a real app when I have the time to try it in Proppy.</p>
The solution🔗</a></h2>
This example will use React, MobX and router5</a>.
router5 is a nice router library that treats routing state like any application state.
Combined with MobX, you can have a store that will contain the routing state trivially without any framework.
I couldn't find an up to date TypeScript definition for router5 so I made one</a>.
I'm not entirely sure whether this is the correct way to write a definition file though so I will wait a bit before making a PR to DefinitelyTyped</a>.</p>
Routing setup🔗</a></h3>
Let's take a very simple routing scheme:</p>
const </span>routes</span>: </span>Array</span><</span>object</span>> </span>= </span>[
</span>  </span>// Logged-in routes
</span>  {name: </span>"home"</span>, path: </span>"/"</span>, canActivate: </span>loggedInRequired</span>, onActivate: </span>dashboardStore</span>.</span>fetch</span>},
</span>
</span>  </span>// Logged-out routes
</span>  {name: </span>"signin"</span>, path: </span>"/signin"</span>},
</span>  {name: </span>"signup"</span>, path: </span>"/signup"</span>},
</span>  {name: </span>"forgot-password"</span>, path: </span>"/forgot-password"</span>},
</span>];
</span>
</span>export </span>type </span>Routes </span>=
</span>  </span>"home"
</span>  </span>| </span>"signin"
</span>  </span>| </span>"signup"
</span>  </span>| </span>"forgot-password"
</span>;
</span></code></pre>
As you can see, nothing magical going on: routes</code> is simply an array of routes, which are plain JavaScript objects themselves.
The Routes</code> type has to be manually updated to match the routes but allows compile-time checking of the routes: a worthy trade-off in my eyes.</p>
The canActivate</code> key corresponds to a lifecycle function</a> of router5.
router5 will call this function before transitioning to the new state, preventing the transition if necessary.
In that case it is simply the following:</p>
const </span>loggedInRequired </span>= </span>() </span>=> </span>(</span>toState</span>: </span>State</span>, </span>fromState</span>: </span>State</span>, </span>done</span>: </span>any</span>) </span>=> </span>{
</span>  </span>// userIsLoggedIn can be whatever you need it to be
</span>  </span>if </span>(</span>userIsLoggedIn</span>()) {
</span>    </span>return </span>true</span>;
</span>  } </span>else </span>{
</span>    </span>// redirect to signin page if the user isn't logged in
</span>    </span>done</span>({redirect: {name: </span>"signin"</span>}});
</span>  }
</span>};
</span></code></pre>
onActivate</code> will be explained in a bit.</p>
Before looking at the router setup, let's have a quick look at the MobX router store:</p>
import </span>{</span>action</span>, </span>observable</span>} </span>from </span>"mobx"</span>;
</span>import </span>{</span>State</span>} </span>from </span>"router5"</span>;
</span>
</span>class </span>RouterStore </span>{
</span>  @</span>observable current</span>: </span>State</span>;
</span>  @</span>observable asyncInProgress </span>= </span>false</span>;
</span>
</span>  </span>// Called after transition
</span>  @</span>action </span>setCurrent</span>(</span>state</span>: </span>State</span>) {
</span>    </span>this</span>.</span>current </span>= </span>state</span>;
</span>    </span>this</span>.</span>asyncInProgress </span>= </span>false</span>;
</span>  }
</span>
</span>  @</span>action </span>startAsyncLoading</span>() {
</span>    </span>this</span>.</span>asyncInProgress </span>= </span>true</span>;
</span>  }
</span>}
</span>
</span>const </span>routerStore </span>= new </span>RouterStore</span>();
</span>export default </span>routerStore</span>;
</span></code></pre>
If you haven't used MobX before, I heavily recommend it and wrote an introduction to it</a> before. In a nutshell,
think of the code above as a simple class that has 2 observable values: current</code> and asyncInProgress</code>.</p>
Ok we got our routes and store, we now need to create a router:</p>
// Router setup
</span>const </span>router </span>= </span>createRouter</span>(</span>routes</span>);
</span>router</span>.</span>usePlugin</span>(</span>browserPlugin</span>(), </span>mobxRouterPlugin</span>);
</span>router</span>.</span>useMiddleware</span>(</span>asyncMiddleware</span>(</span>routes</span>));
</span>router</span>.</span>start</span>();
</span></code></pre>
This does a few things. First we create a router using the routes we defined above. We then add 2 plugins:</p>

browser</code>: a built-in plugin that will update the browser URL and state on route change using the HTML5 history API</li>
mobxRouterPlugin</code>: a very simple custom made plugin shown below that will upate the store on transition success and error</li>
</ul>
import </span>routerStore </span>from </span>"./stores/router"</span>;
</span>
</span>// Tell MobX which page we're on
</span>export </span>function </span>mobxRouterPlugin</span>(</span>router</span>: </span>Router</span>) {
</span>  </span>return </span>{
</span>    </span>onTransitionError</span>: (</span>toState</span>: </span>State</span>) </span>=> </span>{
</span>      </span>// TODO handle that.
</span>    },
</span>    </span>onTransitionSuccess</span>: (</span>toState</span>: </span>State</span>) </span>=> </span>{
</span>      </span>routerStore</span>.</span>setCurrent</span>(</span>toState</span>);
</span>    },
</span>  };
</span>}
</span>(</span>mobxRouterPlugin </span>as </span>PluginFactory</span>).</span>pluginName </span>= </span>"MOBX_PLUGIN"</span>;
</span></code></pre>
How errors are handled is really up to you, I'm focusing on the happy path for that article.</p>
Next up is the asyncMiddleware</code> that handles any pre-loading we need to do.
If a onActivate</code> function on a route is found a route, it assumes it is an async call that returns a promise:</p>
const </span>asyncMiddleware </span>= </span>(</span>routes</span>: </span>Array</span><</span>any</span>>) </span>=> </span>(</span>router</span>: </span>Router</span>) </span>=> </span>(</span>toState</span>: </span>any</span>, </span>fromState</span>: </span>State</span>, </span>done</span>: </span>any</span>) </span>=> </span>{
</span>  </span>const </span>route </span>= </span>routes</span>.</span>find</span>((</span>r</span>) </span>=> </span>r</span>.</span>name </span>=== </span>toState</span>.</span>name</span>);
</span>  </span>// do we have a function to call?
</span>  </span>if </span>(</span>route</span>.</span>onActivate</span>) {
</span>    </span>// Tell the store that will load something, might want to have some visual loading effect
</span>    </span>routerStore</span>.</span>startAsyncLoading</span>();
</span>    </span>return </span>route</span>.</span>onActivate</span>(</span>toState</span>.</span>params</span>)
</span>      .</span>then</span>((</span>res</span>: </span>any</span>) </span>=> </span>{
</span>        </span>// Fail the transition if the call failed
</span>        </span>if </span>(</span>res</span>.</span>error</span>) {
</span>          </span>return </span>done</span>({code: </span>"TRANSITION_ERR"</span>, error: </span>res</span>});
</span>        }
</span>      });
</span>  }
</span>  </span>done</span>();
</span>};
</span></code></pre>
In practice, the onActivate</code> method of the home</code> route will be called before transitioning and will only be completed if the call succeeded.
The store will automatically be notified of the start of an async call and of any successful transition: displaying a loading progress becomes straightforward.</p>
Finally, we start the router which will automatically use the current URL as the current state as we are using the Browser plugin.</p>
Integrating React🔗</a></h3>
Now that we have the routing is up and running, we need to be able to render components depending on the URL and navigate between pages.
Since all the routing state is in a MobX store, this is simply a matter of having a component observe it:</p>
@</span>observer
</span>class </span>App </span>extends </span>React</span>.</span>Component</span><{}, {}> {
</span>  </span>render</span>() {
</span>    </span>if </span>(</span>routerStore</span>.</span>current </span>=== </span>null</span>) {
</span>      </span>return </span>null</span>;
</span>    }
</span>
</span>    </span>let </span>component </span>= </span>null</span>;
</span>    </span>switch </span>(</span>routerStore</span>.</span>current</span>.</span>name </span>as </span>Routes</span>) {
</span>      </span>case </span>"signup"</span>:
</span>        </span>component </span>= </span><</span>SignUp </span>/></span>;
</span>        </span>break</span>;
</span>      </span>case </span>"signin"</span>:
</span>        </span>component </span>= </span><</span>SignIn </span>/></span>;
</span>        </span>break</span>;
</span>      </span>case </span>"forgot-password"</span>:
</span>        </span>component </span>= </span><</span>ForgotPassword </span>/></span>;
</span>        </span>break</span>;
</span>    }
</span>    </span>// A 404 would be quite blank.
</span>    </span>return </span>(
</span>      </span><</span>div className</span>=</span>"app-container"</span>>
</span>        {</span>component</span>}
</span>      </</span>div</span>>
</span>    );
</span>  }
</span></code></pre>
That's it. A simple switch on the name of the current route and we're good to go.</p>
There is a small twist for links though: using a basic <a href="/forgot-password">Forgot?</a></code> will trigger a full reload, unless there's an option I missed.
You will need to use the router.navigate</code> method to navigate instead.
If you are using React you might have a Link</code> component in your project to standardize how links are made and the various styles it can have.
Here's an example for a basic one:</p>
export </span>interface </span>ILinkProps </span>{
</span>  </span>name</span>: </span>Routes</span>;
</span>  </span>params</span>?: </span>object</span>;
</span>  </span>options</span>?: </span>{</span>reload</span>: </span>boolean</span>, </span>refresh</span>: </span>boolean</span>};
</span>}
</span>
</span>class </span>Link </span>extends </span>React</span>.</span>Component</span><</span>ILinkProps</span>, {}> {
</span>  </span>protected static </span>defaultProps </span>= </span>{
</span>    options: {},
</span>    params: {},
</span>  };
</span>
</span>  </span>render</span>() {
</span>    </span>const </span>{</span>name</span>, </span>params</span>} </span>= </span>this</span>.</span>props</span>;
</span>
</span>    </span>// Build the end url
</span>    </span>const </span>href </span>= </span>router</span>.</span>buildPath</span>(</span>name</span>, </span>params </span>as </span>any</span>);
</span>    </span>if </span>(</span>href </span>=== </span>null</span>) {
</span>      </span>// tslint:disable-next-line
</span>      </span>console</span>.</span>error</span>(</span>"<Link> Couldn't make URL for"</span>, </span>name</span>, </span>params</span>);
</span>    }
</span>
</span>    </span>return </span>(
</span>      </span><</span>a href</span>=</span>{</span>href</span>} </span>onClick</span>=</span>{</span>this</span>.</span>onClick</span>.bind(</span>this</span>)}>
</span>        {</span>this</span>.</span>props</span>.</span>children</span>}
</span>      </</span>a</span>>
</span>    );
</span>  }
</span>
</span>  </span>private </span>onClick</span>(</span>event</span>: </span>React</span>.</span>MouseEvent</span><{}>) {
</span>    </span>const </span>{</span>name</span>, </span>params</span>, </span>options</span>} </span>= </span>this</span>.</span>props</span>;
</span>    </span>const </span>comboKey </span>= </span>event</span>.</span>metaKey </span>|| </span>event</span>.</span>altKey </span>|| </span>event</span>.</span>ctrlKey </span>|| </span>event</span>.</span>shiftKey</span>;
</span>
</span>    </span>if </span>(</span>event</span>.</span>button </span>=== </span>0 </span>&& !</span>comboKey</span>) {
</span>      </span>event</span>.</span>preventDefault</span>();
</span>      </span>router</span>.</span>navigate</span>(</span>name</span>, </span>params</span>, </span>options</span>);
</span>    }
</span>  }
</span>}
</span>
</span>export default </span>Link</span>;
</span></code></pre>
Which can be used like so:</p>
<</span>Link </span>name</span>=</span>"forgot-password"</span>>Forgotten password?</</span>Link</span>>
</span></code></pre>
The route name will be checked at compile time as well, no more typos!</p>
The end🔗</a></h2>
Will this work for complex apps?
I don't know but I will certainly try it and report!</p>
Edit: It looks like TypeScript 2.4 will support string enums</a>!
This means we will be able to not duplicate the Routes</code> content and use an enum instead!</p>
Edit2: This approach is now in production! Read up on the follow-up article</a>.</p>


This month in my Rust projects
Unknown — Sun, 23 Apr 2017 00:00:00 +0000
I have just released v2 of jsonwebtoken</a> and
thought a blog post would be a good way to talk about the progress of jsonwebtoken, Tera and Gutenberg this month.</p>
jsonwebtoken🔗</a></h2>
Version 2 is almost a full rewrite, but trying to keep the UX as good as possible.</p>
The following improvements have been made:</p>

use serde</code> instead of rustc_serialize</code>: no brainer as serde</code> is now usable on stable and reached 1.0.0</li>
RSA signing and verification</li>
Validation</li>
</ul>
Validation is the main thing that was missing from version 1 and brings jsonwebtoken</code> to almost parity with libraries
in other languages. It is detailed in the README</a>.</p>
As an aside, the signature of decode</code> is an example of why I would like to have default arguments in functions.
The signature is:</p>
pub fn </span>decode</span><T: DeserializeOwned>(
</span>    </span>token</span>: </span>&</span>str</span>,
</span>    </span>key</span>: </span>&</span>[</span>u8</span>],
</span>    </span>validation</span>: </span>&</span>Validation
</span>) -> </span>Result</span><TokenData<T>>
</span></code></pre>
But I expect Validation</code> to be the default most of the time so the ideal signature would be something like:</p>
pub fn </span>decode</span><T: DeserializeOwned>(
</span>    </span>token</span>: </span>&</span>str</span>,
</span>    </span>key</span>: </span>&</span>[</span>u8</span>],
</span>    validation = </span>&</span>Validation::</span>default() </span>// or whatever the syntax would be
</span>) -> </span>Result</span><TokenData<T>>
</span></code></pre>
And using decode</code> would be cleaner (at least for me):</p>
decode</span>(</span>&</span>token, </span>"key"</span>, </span>&</span>Validation::default());
</span>// VS
</span>decode</span>(</span>&</span>token, </span>"key"</span>);
</span></code></pre>
There is a pre RFC</a> but not much progress has
been made recently.</p>
Thanks a lot to Mike Engel</a> for all the feedback!</p>
Tera🔗</a></h2>

Tera</a> is a template engine based on Jinja2/Django templates</p>
</blockquote>
Tera has gone through 2 versions in April: 0.9.0 and now 0.10.</p>
0.9 fixed a major bug on Windows and 0.10 updated serde</code> to 1.0, no major changes otherwise: Tera is pretty stable now.</p>
Gutenberg🔗</a></h2>

Gutenberg</a> is a static site engine</p>
</blockquote>
Lots of progress this month on Gutenberg!</p>
A short list of the biggest new features:</p>

Shortcodes inspired by Hugo</a></li>
Relative links to your own content: [my last article](./posts/an-article.md)</code></li>
Anchors for titles with an option to insert some HTML to allow behaviour similar to the Github READMEs</li>
Works on Windows!</li>
</ul>
Next up is sorting by weight/order</a> and finishing up
pagination</a>.</p>
Once those features are in, I will probably spend some time making an actual documentation site to ensure it works for sites
more complex than this blog.</p>
If anyone is knowledgeable about Live Reload</a>, I'd like some help tracking down this issue</a>.</p>
Solving this issue in Syntect</a> would also help but I don't have time/motivation for it myself right now.</p>
Otherwise, Gutenberg mostly needs feedback and even feature request for things I didn't consider yet.</p>


Announcing Gutenberg, a static site engine
Unknown — Sat, 25 Mar 2017 00:00:00 +0000
Why would we possibly want another static site engine?</em> I already hear some say.
That's a very valid question!</p>
I currently have 6 static sites live:</p>

wearewizards.io (link now dead)</li>
blog.wearewizards.io (link now dead)</li>
vincent.is (link now dead; redirecting to vincentprouillet.com)</li>
proppy.io  (link now dead)</li>
proppy.io/blog (link now dead)</li>
pixelspa.com</a></li>
</ul>
Those are all using Hugo</a>, except the blog you're reading
that moved to Gutenberg a couple of days ago.</p>
Hugo in itself is pretty great: I switched from Pelican for the speed and the stand-alone binary and
stayed for the instant live reload. The huge pain point for me with Hugo is the Go template
engine: I find it so bad that it turns a great experience into a, well, sad experience.</p>
When I first looked at Rust a couple of years ago, I thought that a static site engine could be a nice first
program to write to learn the language. Sadly, I didn't find a template engine I liked at the time which
prompted me to write my own, Tera</a>.</p>
Now that Tera is getting more mature and my frustration with Go templates grows, I started
working again on the static site engine a few weeks ago and it got to a point where it's usable.</p>
It's called Gutenberg</strong> and is now available in a 0.0.2 version on crates.io and Github</a>.
It seems AppVeyor is running into some issue with curl so I haven't been able to test it on Windows yet but
it should work on Linux and OSX. Binaries are built using the very nice trust</a> project.</p>
The features🔗</a></h2>
Gutenberg is opinionated (only TOML for configuration, only Tera for templates, only CommonMark for content) but is flexible
enough to let you build all kinds of sites, from landing pages to knowledge bases, not only blogs.</p>
Features in no particular order are:</p>

CommonMark for content</li>
Categories and Tags automatic page creation (easy to disable)</li>
Automatic RSS feed (easy to disable)</li>
Built-in server with fast live reload (a bit buggy currently)</li>
Supports having assets next to the content: no need to put everything in a static</code> folder</li>
Explicit sections that can have their own page and have access to potential subsections: this allows making pages like https://easyengine.io/tutorials/</a>
which are a big table of contents over several sections</li>
Good template engine: I'm a bit biased there</li>
Simple to use: no surprises, everything is explicit except from the default templates used</li>
</ul>
More information is available on the README</a> and better documentation will come
once the tool is in a more stable shape.</p>
What's next🔗</a></h2>
As the 0.0.2 version number indicates, Gutenberg is still a work-in-progress. Despite
that, it fills almost all my static engine needs. There are a few things that will need
to be done before being ready for a 0.1 though:</p>

Find and fix bugs, add tests and benchmarks</li>
Make it faster: parallelize if possible</li>
Pagination: still debating the best way to set up that up in a Github issue</a></li>
Add an equivalent to Hugo shortcodes</a>: they make it easy to embed
some HTML in your markdown without repeating HTML all the time, e.g. a youtube video could be added to a page like so {{ youtube(id=87238) }}</code>
and the renderer will insert whatever template we defined for the youtube</code> shortcode.</li>
</ul>
And for after the 0.1 release:</p>

Built-in Jupyter renderer would be nice</li>
Proper documentation site</li>
</ul>
The current blocker to parallelization is that syntect</a>, the
great library I'm using for syntax highlighting is not thread-safe. There is an issue</a> open
but I haven't had the time or energy to look/fix that yet.
It should be fairly straightforward to add Rayon once it's fixed, if the benchmarks show a significant difference.</p>
How does it look in practice🔗</a></h2>
You can have a look at the source of this site</a>.</p>
This site is very simple: a blog and a couple of other pages but it should give some ideas.</p>
Enjoy!🔗</a></h2>
Obviously, any feedback is welcome!
While the general design and current features are unlikely to change, I'd be happy to cover
more use-cases if possible.</p>
Check it out on Github: Gutenberg</a></p>


My current frontend setup is pretty neat
Unknown — Sat, 28 Jan 2017 00:00:00 +0000
From time to time, I see someone on Github forking or starring the Angular boilerplate I made and was using 2 years ago.
As everyone knows, time in JavaScript-land tends to operate in a different scale: something done 2 years ago
is prehistoric and a generation or two of frameworks went by.</p>
I have been using React</a> for about a year now, mainly for the frontend
of Proppy and some experiments on the side. While the churn for the libraries during that year
reached a level I had never seen before, it seems to have stabilised a bit.
That or I stopped trying to follow JS news, who knows.</p>
Since many people might suffer from analysis paralysis</a>, I decided to document
my own choices to help. It will also provide a good laugh for people find that article in a few months/years, missing the date
and thinking "people are STILL using X?".</p>
Package manager🔗</a></h2>
Yes, you can even choose your package manager in JavaScript!</p>
npm</code> is fine as long as you remember to shrinkwrap</a> and don't mind slow installs.</p>
I settled on yarn</a>, which does the right thing by default: a lock file and deterministic installs.
Installing packages is also faster than npm</code>, which is a nice bonus. Despite how recent it is, I haven't run into bugs yet.</p>
Module bundler🔗</a></h2>
I use Webpack</a>.
Not much to say here, once you understand how to configure it - and it might take a while - it
is easy to get going (AKA cp ../previous_project/webpack.config.js .</code>).</p>
I also like to use html-webpack-plugin</a>.</p>
Language🔗</a></h2>
I use TypeScript</a>.
If you are using plain Javascript or just Babel, I strongly encourage you
to try something that adds types, be it Elm</a>, Flow</a>, TypeScript or something else like
ScalaJS.</p>
Some people view types as hindrance but they make me so much more productive:</p>

Object shapes and function arguments are documented and is enforced by the compiler</li>
I can do sweeping changes in a codebase without any trouble</li>
Fewer errors: trying to call a function that only takes a string</code> with a potentially undefined</code> argument? Nope</li>
</ul>
Elm catch phrase is "no runtime exceptions" but I'd argue it is also valid for anything sufficiently typed.</p>
The big advantage TypeScript has over the alternatives mentioned is the huge community
and type definitions are available for tons of libraries.</p>
If you are planning to use TypeScript, make sure you start your project with a very strict config.
I use the following for new projects:</p>
{
</span>  </span>"compilerOptions"</span>: {
</span>    </span>"target"</span>: </span>"es5"</span>,
</span>    </span>"module"</span>: </span>"commonjs"</span>,
</span>    </span>"jsx"</span>: </span>"react"</span>,
</span>    </span>"experimentalDecorators"</span>: </span>true</span>,
</span>    </span>"noImplicitAny"</span>: </span>true</span>,
</span>    </span>"strictNullChecks"</span>: </span>true</span>,
</span>    </span>"noUnusedParameters"</span>: </span>true</span>,
</span>    </span>"noUnusedLocals"</span>: </span>true</span>,
</span>    </span>"sourceMap"</span>: </span>true
</span>  },
</span>  </span>"exclude"</span>: [
</span>    </span>"node_modules"
</span>  ]
</span>}
</span></code></pre>
If you are converting a large app to TS, noImplicitAny</code> might be a pain so only
set it to true</code> when done.</p>
I also use tslint</a> for linting, which comes with a default good config.</p>
View🔗</a></h2>
As mentioned in the introduction, I use React.
I've also been following/contributing a bit to Inferno</a> as an alternative but it doesn't
have great type definitions, which is a deal breaker for me.</p>
I would also recommend to mostly write your own components if design is an important factor and you have time for it instead
of using third-party components. Unless it's something like an admin or a private site, then go ahead and use a material library
or any UI library.</p>
State management🔗</a></h2>
I've settled on MobX</a> and am pretty happy about it.
I wrote about MobX and going from Redux</a> before so I'm not going to repeat myself here.</p>
In short: very simple to use, fully typed and not verbose at all.
A pleasure after using Redux</a>.</p>
Testing🔗</a></h2>
I'm currently using Mocha/Chai with Karma</a> in Proppy and it's working well.
I have heard good things about recent versions of Jest</a> but haven't had the time to look at it yet,
it is the next item on the TO TRY list.</p>
CSS🔗</a></h2>
I am using Sass</a> with some postcss plugins like Lost</a>
or Autoprefixer</a>. If you are targeting evergreen browsers, autoprefixer</code> won't be needed.</p>
I haven't seen a single CSS-in-JS library that convinced me.
The closest was TypeStyle</a> but is ultimately failing because it has a runtime
overhead. I'll address that in the "What am I missing" section later on.</p>
Prototyping🔗</a></h2>
I recently discovered storybook</a>. If you are using React and didn't hear about it or tried it,
stop reading this article and go play with it. It's that glorious.</p>
Rather than explaining how it works, have a look at Airbnb date picker storybook</a>.</p>
Storybook allows you to easily develop components and see all their potential usages in one place, as well as showing an always
up-to-date style guide.</p>
What am I missing🔗</a></h2>
I'm still missing a few things and welcome any input.</p>
Compile-time styling🔗</a></h3>
As mentioned before, TypeStyle is really close to a good solution for styling but for me,
a styling tool should have no runtime cost. CSS is working well and having JavaScript do its job doesn't really make sense.</p>
I raised an issue</a> for that but it seems rewriting AST is not
available in TypeScript yet so a TS plugin that extracts those call is not doable for now.</p>
Animations🔗</a></h3>
I'm still unsure how to easily</em> add animations. animate</a> looks like a good
candidate though.</p>
TL;DR🔗</a></h2>
My starter package.json</code>:</p>
{
</span>  </span>"name"</span>: </span>"frontend"</span>,
</span>  </span>"version"</span>: </span>"1.0.0"</span>,
</span>  </span>"main"</span>: </span>"index.js"</span>,
</span>  </span>"scripts"</span>: {
</span>    </span>"clean"</span>: </span>"rimraf -- dist"</span>,
</span>    </span>"dev"</span>: </span>"webpack-dev-server"</span>,
</span>    </span>"build"</span>: </span>"webpack"</span>,
</span>    </span>"storybook"</span>: </span>"start-storybook -p 6006"</span>,
</span>    </span>"build-storybook"</span>: </span>"build-storybook"
</span>  },
</span>  </span>"devDependencies"</span>: {
</span>    </span>"@kadira/react-storybook-decorator-centered"</span>: </span>"^1.0.0"</span>,
</span>    </span>"@kadira/storybook"</span>: </span>"^2.21.0"</span>,
</span>    </span>"@types/classnames"</span>: </span>"^0.0.32"</span>,
</span>    </span>"@types/react"</span>: </span>"^15.0.0"</span>,
</span>    </span>"@types/react-dom"</span>: </span>"^0.14.20"</span>,
</span>    </span>"autoprefixer"</span>: </span>"^6.6.0"</span>,
</span>    </span>"css-loader"</span>: </span>"^0.26.1"</span>,
</span>    </span>"html-webpack-plugin"</span>: </span>"^2.24.1"</span>,
</span>    </span>"node-sass"</span>: </span>"^4.1.1"</span>,
</span>    </span>"rimraf"</span>: </span>"^2.5.4"</span>,
</span>    </span>"sass-loader"</span>: </span>"^4.1.1"</span>,
</span>    </span>"ts-loader"</span>: </span>"^2.0.0"</span>,
</span>    </span>"tslint"</span>: </span>"^4.2.0"</span>,
</span>    </span>"tslint-loader"</span>: </span>"^3.3.0"</span>,
</span>    </span>"typescript"</span>: </span>"^2.1.4"</span>,
</span>    </span>"webpack"</span>: </span>"2.2.0-rc.4"</span>,
</span>    </span>"webpack-dev-server"</span>: </span>"2.2.0-rc.0"
</span>  },
</span>  </span>"dependencies"</span>: {
</span>    </span>"classnames"</span>: </span>"^2.2.5"</span>,
</span>    </span>"mobx"</span>: </span>"^3.0.0"</span>,
</span>    </span>"mobx-react"</span>: </span>"^4.1.0"</span>,
</span>    </span>"react"</span>: </span>"^15.4.1"</span>,
</span>    </span>"react-dom"</span>: </span>"^15.4.1"
</span>  }
</span>}
</span></code></pre>


Releasing Tera 0.6 and thoughts on a validation crate
Unknown — Mon, 26 Dec 2016 00:00:00 +0000
Tera</a> 0.6 has been released on crates.io</a>!</p>
I will let the changelog speaks for itself:</p>
BREAKING CHANGES🔗</a></h4>

not</code> is now a Tera keyword</li>
</ul>
Others🔗</a></h4>

Added #![deny(missing_docs)]</code> to the crate</li>
Added Tera::one_off</code> to parse and render a single template</li>
Added not</code> operator in conditions to mean falsiness (equivalent to !</code> in Rust)</li>
Remove specific error message when using ||</code> or &&</code></li>
Improved performances for parsing and rendering (~5-20%)</li>
Added precision</code> arg to round</code> filter</li>
Added date</code> filter to format a timestamp to a date(time) string</li>
</ul>
Nothing too exciting in that release except finally handling not</code> in expressions.</p>
I don't foresee big changes in the API coming soon anymore as we approach feature completeness from my point of view.</p>
The 2 main things still lacking are:</p>

custom tags</strong>: we would need to expose the renderer or the AST somehow</li>
i18n</strong>: no mature i18n libraries in Rust as far as I'm aware</li>
</ul>
I am not using any of those in my own projects but anyone wanting to discuss them is welcome.</p>
Validation crate🔗</a></h2>
I've been working through the requirements.txt</code> of Proppy to decide what crate to work on in Rust.</p>
The next one will probably be a crate similar to the marshmallow</a> library.
Since Serde can handle the serialization/deserialization aspect already, it will focus only on actual validation with an API looking like
that:</p>
#[</span>derive</span>(Debug, Deserialize, Validate)]
</span>struct </span>SignupData </span>{
</span>    #[</span>validate</span>(email)]
</span>    </span>email</span>: String,
</span>    #[</span>validate</span>(url)]
</span>    </span>site</span>: String,
</span>    #[</span>validate</span>(custom</span>=</span>"validate_unique_username"</span>)]
</span>    #[</span>validate</span>(</span>length</span>(min</span>=</span>2))]
</span>    </span>username</span>: String,
</span>    #[</span>validate</span>(</span>length</span>(min</span>=</span>8, max</span>=</span>255), custom</span>=</span>"validate_common_passwords"</span>)]
</span>    </span>password</span>: String,
</span>}
</span></code></pre>
A non-goal of that crate will be error messages as it's always a pain to handle. Errors will be referenced by a keyword
and it will be up to the frontend or the backend to write error messages in the correct format for that application.</p>
The first step is figuring out how macros 1.1 work but once it's done, it seems like it will be a fairly small crate.</p>
See you in 2017!</p>


Handling errors in Rust
Unknown — Thu, 15 Dec 2016 00:00:00 +0000
Error handling in Rust is pretty straightforward.</p>
The standard library comes with the Result</code> type which has the following definition:</p>
#[</span>must_use</span>]
</span>pub enum </span>Result</span><T, E> {
</span>    </span>Ok</span>(T),
</span>    </span>Err</span>(E),
</span>}
</span></code></pre>
In short, Result</code> can either be OK with a value T</code> or be an error with value E</code>.
The #[must_use]</code> annotation means that the compiler will warn you if you ignore a Result</code>.</p>
No more forgetting to catch that one exception or a if err != nil { return nil, err }</code>.</p>
Handling Result🔗</a></h2>
Let's have a look a small program to see the various way of creating and handling errors in Rust.
Follow this playground link</a> to run and play with the examples below.</p>
use </span>std::fmt;
</span>use </span>std::io;
</span>use </span>std::error::Error;
</span>
</span>// Our set of errors for that program
</span>#[</span>derive</span>(Debug)]
</span>enum </span>MyErrors </span>{
</span>    BadMood,
</span>    </span>// Badly implemented IO error
</span>    FileFailure(</span>String</span>),
</span>    </span>// Correctly implemented IO error
</span>    FileFailure2(io::Error),
</span>}
</span>
</span>// Impl display so we can have nice strings to print
</span>impl </span>fmt::Display </span>for </span>MyErrors </span>{
</span>    </span>fn </span>fmt</span>(</span>&</span>self</span>, </span>f</span>: </span>&</span>mut </span>fmt::Formatter) -> fmt::Result {
</span>        </span>match *</span>self </span>{
</span>            MyErrors::FileFailure(</span>ref</span> err) </span>=> </span>write!</span>(f, </span>"File creation failed: </span>{:?}</span>"</span>, err),
</span>            MyErrors::FileFailure2(</span>ref</span> err) </span>=> </span>write!</span>(f, </span>"File creation failed: </span>{:?}</span>"</span>, err),
</span>            MyErrors::BadMood </span>=> </span>write!</span>(f, </span>"Nothing wrong, just wanted to error."</span>),
</span>        }
</span>    }
</span>}
</span>
</span>impl </span>Error </span>for </span>MyErrors </span>{
</span>    </span>fn </span>description</span>(</span>&</span>self</span>) -> </span>&</span>str </span>{
</span>        </span>match *</span>self </span>{
</span>            MyErrors::BadMood </span>=> </span>"bad mood"</span>,
</span>            MyErrors::FileFailure(</span>ref</span> err) </span>=> </span>"file failure"</span>,
</span>            MyErrors::FileFailure2(</span>ref</span> err) </span>=> </span>"file failure"</span>,
</span>        }
</span>    }
</span>
</span>    </span>fn </span>cause</span>(</span>&</span>self</span>) -> </span>Option</span><</span>&</span>Error> {
</span>        </span>match *</span>self </span>{
</span>            MyErrors::FileFailure(</span>_</span>) </span>=> </span>None</span>,
</span>            </span>// the cause is the io::error
</span>            MyErrors::FileFailure2(</span>ref</span> err) </span>=> </span>Some</span>(err),
</span>            MyErrors::BadMood </span>=> </span>None</span>,
</span>        }
</span>    }
</span>}
</span>
</span>
</span>impl </span>From</span><io::Error> </span>for </span>MyErrors </span>{
</span>    </span>fn </span>from</span>(</span>err</span>: io::Error) -> MyErrors {
</span>        MyErrors::FileFailure2(err)
</span>    }
</span>}
</span>
</span>
</span>fn </span>will_succeed</span>() -> </span>Result</span><</span>bool</span>, MyErrors> {
</span>    </span>Ok</span>(</span>true</span>)
</span>}
</span>
</span>fn </span>will_fail</span>(</span>filename</span>: </span>&</span>str</span>) -> </span>Result</span><(), MyErrors> {
</span>    </span>Err</span>(MyErrors::FileFailure(</span>format!</span>(</span>"Failed to created </span>{}</span>"</span>, filename)))
</span>}
</span>
</span>fn </span>do_something</span>() -> </span>Result</span><(), MyErrors> {
</span>    </span>match </span>will_fail</span>(</span>"index.html"</span>) {
</span>        </span>Ok</span>(</span>_</span>) </span>=> </span>{
</span>            </span>// we don't care about the result value, it's an empty tuple
</span>            </span>return </span>Ok</span>(());
</span>        }
</span>        </span>Err</span>(e) </span>=> </span>{
</span>            </span>println!</span>(</span>"Error while creating a file:</span>\n {}</span>"</span>, e);
</span>        }
</span>    };
</span>
</span>    </span>// Equivalent to match above
</span>    </span>if </span>let </span>Err</span>(e) </span>= </span>will_fail</span>(</span>"index.html"</span>) {
</span>        </span>println!</span>(</span>"Error while creating a file:</span>\n {}</span>"</span>, e);
</span>    } </span>else </span>{
</span>        </span>return </span>Ok</span>(());
</span>    }
</span>    </span>// method 1 to propagate errors: try! macro
</span>    </span>let</span> did_succeed </span>= </span>try!</span>(</span>will_succeed</span>());
</span>    </span>// method 2 to propagate errors: question mark operator
</span>    </span>let</span> did_succeed2 </span>= </span>will_succeed</span>()</span>?</span>;
</span>
</span>    </span>Ok</span>(())
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>do_something</span>();
</span>}
</span></code></pre>
About half of the lines are about defining errors, we will see how to reduce that boilerplate in the following section.
If you want to read more on that, the error handling section</a> in the Rust book is very good.</p>
The interesting part in that code is the body of the do_something</code> function which showcases the various ways of
handling Result</code>.</p>
You can be in 2 situations when handling errors:</p>

you want to handle them immediately</li>
you want to do an early return and pass them back to the caller</li>
</ul>
The match</code> and if let</code> constructs are equivalent in this case and  used if you are in the first situation.</p>
The try!</code> and question mark operator are also equivalent: they return the error if there is one and unpacks the Ok</code> value
otherwise.</p>
?</code> was stabilised in Rust 1.13 (released about one month before this post) and is somewhat controversial
as some think that error handling is hidden when using it.</p>
I like the ?</code> operator myself since I think it makes the code neater but I let you be the judge:</p>
let</span> val </span>= </span>try!</span>(</span>try!</span>(</span>try!</span>(</span>do_something</span>()).</span>do_something_else</span>()).</span>finish</span>());
</span>// or cleaner
</span>let</span> a </span>= </span>try!</span>(</span>do_something</span>());
</span>let</span> b </span>= </span>try!</span>(a.</span>do_something_else</span>());
</span>let</span> val </span>= </span>try!</span>(b.</span>finish</span>());
</span>
</span>let</span> val </span>= </span>do_something</span>()</span>?</span>.</span>do_something_else</span>()</span>?</span>.</span>finish</span>();
</span></code></pre>
Avoiding error boilerplate🔗</a></h2>
As you saw from the example above, defining your own errors is very verbose.</p>
After experimenting on my own at first, I found the quick-error</a> crate which
makes creating your own error and extending built-in ones like the io::Error</code> in the previous section a breeze.
This was my go-to crate for error handling, until reading this article</a>
about error-chain</a>.</p>
error-chain</code> builds on quick-error</code> and makes it even more painless.</p>
I have switched Tera</a> 0.5 to use error-chain</a> and am very
happy about the end result.</p>
The errors.rs</code> file in Tera went from ~80 lines</a>
and lots of custom errors to:</p>
error_chain! </span>{
</span>    errors {}
</span>}
</span></code></pre>
There is nothing you might say. And you would be somewhat correct!
Using the error_chain!</code> macro gives me Result</code>, ResultExt</code> (a trait), ErrorKind</code> and Error</code> but I didn't define any
custom errors myself.</p>
It's obviously not always empty though, here's the errors.rs</code> of a static site engine using Tera:</p>
use</span> tera;
</span>
</span>
</span>error_chain! </span>{
</span>    links {
</span>        </span>// Links Tera errors to that crate
</span>        Tera(tera::Error, tera::ErrorKind);
</span>    }
</span>
</span>    foreign_links {
</span>        </span>// Link with errors not defined with error-chain
</span>        Io(::std::io::Error);
</span>    }
</span>
</span>    errors {
</span>        </span>// I'm using this one lots of time so creating it there to keep it DRY
</span>        InvalidConfig {
</span>            </span>description</span>(</span>"invalid config"</span>)
</span>            </span>display</span>(</span>"The config.toml is invalid or is using the wrong type for an argument"</span>)
</span>        }
</span>    }
</span>}
</span></code></pre>
The article linked previously made me realise that you need custom errors in 2 occasions: the user of the library will pattern match on them or you want
to avoid repeating yourself like the InvalidConfig</code> above.</p>
In Tera case, I was able to replace all the errors with bail!</code> macro that comes with error-chain</code>.
This is a very simple macro that works similarly to println!</code> except it returns an error with the text given:</p>
if</span> something_is_wrong {
</span>    </span>bail!</span>(</span>"Something wrong happened while doing {:?}"</span>, action);
</span>}
</span>
</span>// expands to
</span>if</span> something_is_wrong {
</span>    </span>return </span>Err</span>(</span>format!</span>(</span>"Something wrong happened while doing </span>{:?}</span>"</span>, action).</span>into</span>());
</span>}
</span></code></pre>
It doesn't look like much but using stringly typed errors saves a lot of time and makes you write better errors
at the same time as you can write very specific errors without any boilerplate.</p>
But the killer feature of error-chain</code> is to chain errors, as its name implies.
You often want to add context to errors and chaining allows just that.</p>
The easiest example is a function to open a file: Rust doesn't include the filename in the error but you usually want it if
you are going to display it.</p>
use </span>errors::ResultExt;
</span>
</span>File::open(path)
</span>    .</span>chain_err</span>(|| </span>format!</span>(</span>"Failed to open </span>{}</span>."</span>, path))</span>?
</span>    .</span>read_to_string</span>(</span>&</span>mut</span> content)</span>?</span>;
</span></code></pre>
chain_err</code> is coming from the ResultExt</code> and is where the magic happens. If an error in File::open</code> happens,
it will create a new error, storing the one caused by File::open</code> as its cause. Errors can be chained multiple times, allowing you
to annotate errors at several levels and giving detailed error messages.</p>
Printing all chained errors is as simple as the code below:</p>
println!</span>(</span>"Error: </span>{}</span>"</span>, e);
</span>for</span> e </span>in</span> e.</span>iter</span>().</span>skip</span>(</span>1</span>) {
</span>    </span>println!</span>(</span>"Reason: </span>{}</span>"</span>, e);
</span>}
</span></code></pre>
I'm liking this approach quite a lot and will be using it for all my projects for the foreseeable future!</p>


Releasing Tera 0.4 and state of my other crates
Unknown — Fri, 02 Dec 2016 00:00:00 +0000
I'm happy to announce Tera</a> 0.4 has been released on crates.io</a>!</p>
Tera is a template engine based on Jinja2</a> and the Django template language</a>.
I say based as it's not a 1:1 port and has some minor differences with them but is close enough that you should be able
to use the same syntax highlighting.</p>
This version introduces the last big features:</p>

Macros</a></li>
Multiple level extend, super() and nested blocks</a></li>
Autoescape</a></li>
</ul>
It also adds the filesizeformat</code> filter thanks to the humansize crate</a>.</p>
Some bits are experimental (named endblock/endmacro, kwargs only) and subject to changes depending on feedback.</p>
There are probably features that others deem essential (please create an issue</a> if you can think of one missing!) but for my own use case it seems feature complete, apart from
the missing not</code> operator in conditions. Custom tags would be nice too.</p>
The focus for the next version will be on:</p>

fixing the inevitable bugs</li>
add the not</code> operator</li>
improving documentation: a website and more examples</li>
improving error handling and reporting (maybe error-chain</a> could help there?)</li>
optimizations and code cleanup</li>
</ul>
As you can see, no new big features planned, it will be mostly polishing.</p>
To ensure Tera is easy to use, I'm thinking of making a static site engine using it but that will depend on how much free time I have.
I'm currently using Hugo</a> for all my sites but the Golang template engine is godawful.</p>
Making the templates compile to Rust functions is still not planned in the near future.
Check out Maud</a> or horrorshow</a> if you want type-safe HTML.</p>
If you want to help you have 2 options: use it and report bugs and/or look at the issues tagged for the 0.5 milestone on github</a>.
The code is fairly clean, commented and has lots of tests so it should be easy to jump in.</p>
Thanks to SergioBenitez</a> and yonran</a> for the help!</p>
Other crates🔗</a></h2>
bcrypt (0.1.2)🔗</a></h3>
This one has an explicit name and is stable.
I was thinking of extracting the bcrypt specific code from rust-crypto</a>
but someone already started on that: https://github.com/RustCrypto</a> so I'll just wait.</p>
dbmigrate (0.2.7)🔗</a></h3>
A CLI tool to general and manage SQL migrations for MySQL, SQLite and Postgres.
It is stable and I don't foresee the API or the migration file format changing so I will probably promote it to 1.0 soon.</p>
jsonwebtoken (1.1.5)🔗</a></h3>
Strongly typed JWT library. I like the current API but a few more features are planned for 2.0:</p>

moving to Serde from rustc-serialize</li>
implementing the missing algorithms</li>
</ul>
Issues are created on the github repo</a> so feel free to take one of these before I get to them.</p>
vat (0.1.0)🔗</a></h3>
Validate EU VAT number and VAT rates for each country. Still not entirely sure why I made that crate but I think I'll try switching it
to reqwest</a> when I have time.</p>
I also never got around handling errors from the VIES API since it was always working when I was looking at it and they don't (AFAIK) detail
their error messages anywhere.</p>


A MobX introduction and case study
Unknown — Tue, 01 Nov 2016 00:00:00 +0000
MobX</a> (previously mobservable) is a state management library for JavaScript frontend application. This article introduces it with examples as well as showing how it works in a real app with TypeScript. It is based on a talk I gave at the Osaka Web designers and developers meetup recently.</p>
What is MobX and why should I look into it🔗</a></h2>
MobX?🔗</a></h3>
Let's start by explaining what is MobX and how it works. It's presented as using Transparent Functional Reactive Programming.</p>
Now, FRP is a very controversial term as everyone seems to have their own definition so let's forget about that and look at a illustration from the MobX docs (click on it to open in a new tab and get full size or open this link</a>).</p>

    
        
    </a>
</div>
In short, actions modify the state, which triggers reactions. Part of the state can be derived automatically, such as the number of tasks left to do in a TODO list to take the example of the picture above.
What sets MobX apart from other Observable implementations is the transparent part. Reactions observe which observables you are using and subscribe to them automatically, without you having to explicitely subscribe to those.</p>
Before we continue, a few more things:</p>

while some of the examples use React, MobX is not tied to any particular framework</li>
it is written in TypeScript so you get type definitions out of the box if you are using TypeScript</li>
the learning curve is very small and you will be able to start an app by the end of that article</li>
</ul>
Why would I use it instead of Redux/ImmutableJS or library X?🔗</a></h3>
This part is written from my experience using both Redux/ImmutableJS and MobX with React in Proppy, our app to write proposals for freelancers and small agencies/companies. Its frontend is written in TypeScript, which was one of a big reason to moving to MobX as we will see in a bit.</p>
Our issues with Redux/ImmutableJS were twofold.</p>
The first issue was that it is very verbose. You need to write an action, the reducer function, a selector and then connect the actions and the data on the React components.</p>
The second issue only occurs if you are using TypeScript like us. You also need to add the types of actions and data at each step and sometimes even repeat them if you are passing down actions to dumb components. We were also using ImmutableJS records with maps in them which meant the code was very often stringly typed. For example, getting a value using .getIn(["blocks", id, "data", "value"])</code> was common and there was no typecheck whatsoever.</p>
With MobX we only have to mention the types and, as we will see when showing examples of Proppy, get full typechecking as we are only dealing with plain JavaScript objects.</p>
Note that using MobX means you have to give up immutability, which could be a showstopper for you.</p>
MobX by example🔗</a></h2>
This section is a brief introduction to MobX. If you have already used it, you can safely skip to the next section to see some patterns/snippets from a live application.</p>
Note that I will use ES6 syntax and decorators throughout the examples but it works in plain ES5 as well.</p>
Observing arrays and map changes with autorun🔗</a></h3>
Let's start with observing arrays and maps, as it constitutes a big chunk of what we would want
to observe.</p>
import </span>{ </span>observable</span>, </span>asMap</span>, </span>autorun </span>} </span>from </span>"mobx"</span>;
</span>
</span>// becomes an ObservableArray (same API as normal array)
</span>const </span>numbers </span>= </span>observable</span>([</span>1</span>,</span>2</span>,</span>3</span>]);
</span>// becomes an ObservableMap (same API as Map)
</span>const </span>users </span>= </span>observable</span>(</span>asMap</span>({</span>"bob"</span>: </span>"bob"</span>}));
</span></code></pre>
To show the changes to observable values, we will use the autorun</code> function provided by the mobx package. This function takes a function as argument and call it once to detect which observables are being used in it and subscribe to them.</p>
autorun</span>(() </span>=> </span>{
</span>  </span>console</span>.</span>log</span>(</span>"autorun!"</span>, </span>numbers</span>.</span>toJS</span>(), </span>users</span>.</span>toJS</span>());
</span>});
</span>// initial run: prints autorun! [1,2,3] {"bob": "bob"}
</span>numbers</span>.</span>push</span>(</span>4</span>);
</span>// prints autorun! [1,2,3,4] {"bob": "bob"}
</span>users</span>.</span>set</span>(</span>"jane"</span>, </span>"jane"</span>);
</span>// prints autorun! [1,2,3,4] {"bob": "bob", "jane": "jane"}
</span></code></pre>
We will show in the next section that autorun</code> doesn't actually run everytime any observable is modified like the example above might indicate but only when one of those used in the function are modified.</p>
Observing class properties and transactions🔗</a></h3>
The other thing that we typically want to observe are class properties.</p>
import </span>{ </span>observable</span>, </span>autorun </span>} </span>from </span>"mobx"</span>;
</span>
</span>class </span>Meetup </span>{
</span>  @</span>observable name</span>;
</span>  @</span>observable numberPeople</span>;
</span>
</span>  </span>constructor</span>(</span>name</span>, </span>numberPeople</span>) {
</span>    </span>this</span>.</span>name </span>= </span>name</span>;
</span>    </span>this</span>.</span>numberPeople </span>= </span>numberPeople</span>;
</span>  }
</span>}
</span>
</span>
</span>const </span>thisMeetup </span>= new </span>Meetup</span>(</span>"Osaka Web designers and developers"</span>, </span>0</span>);
</span>autorun</span>(() </span>=> </span>{
</span>  </span>console</span>.</span>log</span>(</span>thisMeetup</span>.</span>numberPeople </span>+ </span>" people"</span>);
</span>});
</span>thisMeetup</span>.</span>numberPeople </span>= </span>1</span>;
</span>// prints "1 people"
</span></code></pre>
In that example, both name</code> and numberPeople</code> are observable properties of the thisMeetup</code> object but only numberPeople</code> is used in the autorun</code> function. Therefore, the following snippet will not print anything:</p>
thisMeetup</span>.</span>name </span>= </span>"Hello"</span>;
</span>// doesn't print anything
</span></code></pre>
Remember the T part of TFRP? MobX automatically figured out which observable to subscribe to and has done so transparently.</p>
Reactions are synchronous so you might wonder how to avoid "useless" reactions, e.g. when setting multiple observables at once such as when receiving a response from a AJAX request. transaction</code> solves that issue by not triggering reactions until the end of the function.</p>
transaction</span>(() </span>=> </span>{
</span>  </span>thisMeetup</span>.</span>numberPeople </span>= </span>2</span>;
</span>  </span>thisMeetup</span>.</span>numberPeople </span>= </span>3</span>;
</span>  </span>thisMeetup</span>.</span>numberPeople </span>= </span>4</span>;
</span>});
</span>// print "4 people"
</span></code></pre>
In the example above, autorun</code> only runs once: with numberPeople</code> equal to 4, not with the intermediate 2 and 3.</p>
Computed values🔗</a></h3>
In some cases, data can be derived directly from the state. To take a simplified example from Proppy, we are going to look at a row in a cost table: we have quantity and unit price and can therefore automatically calculate the total.
computed</code> is lazy (won't be evaluated unless needed in a reaction) and it is memoized (if the observables used inside didn't change, it doesn't need to re-run and can return the current value).</p>
class </span>TableRow </span>{
</span>  @</span>observable quantity </span>= </span>0</span>;
</span>  @</span>observable price </span>= </span>0</span>;
</span>
</span>  </span>constructor</span>(</span>price</span>) {
</span>    </span>this</span>.</span>price </span>= </span>price
</span>  }
</span>
</span>  </span>// a getter
</span>  @</span>computed </span>get </span>total</span>() {
</span>    </span>return </span>this</span>.</span>price </span>* </span>this</span>.</span>quantity</span>;
</span>  }
</span>}
</span>
</span>const </span>row </span>= new </span>TableRow</span>(</span>10</span>);
</span>console</span>.</span>log</span>(</span>row</span>.</span>total</span>);
</span>// prints 0 (since 10x0=0)
</span>row</span>.</span>quantity </span>= </span>10</span>;
</span>// Only computed on the call
</span>console</span>.</span>log</span>(</span>row</span>.</span>total</span>);
</span>// prints 100
</span>// Not recomputed if the observables used didn't change
</span>console</span>.</span>log</span>(</span>row</span>.</span>total</span>)
</span>// prints 100
</span></code></pre>
Note that @computed</code> can only be used on getter</a> in a class.</p>
Actions🔗</a></h3>
Actions are functions that modify the state.
While, as shown in the previous examples, we can simply modify the object directly, it is not the recommended way to do so.</p>
The recommended way is to wrap any actions that modify the state with the action</code> function or decorator. This will accomplish a few things:</p>

wrap the function in a transaction automatically</li>
provide debugging info for that state change that can be displayed in dev tools</li>
</ul>
You can force your app to only modify state through actions by using useStrict(true)</code> in your app.</p>
useStrict</span>(</span>true</span>);
</span>
</span>class </span>TableRow </span>{
</span>  @</span>observable quantity </span>= </span>0</span>;
</span>  </span>price </span>= </span>0</span>;
</span>
</span>  </span>constructor</span>(</span>price</span>) {
</span>    </span>this</span>.</span>price </span>= </span>price
</span>  }
</span>
</span>  </span>// a getter
</span>  @</span>computed </span>get </span>total</span>() {
</span>    </span>return </span>this</span>.</span>price </span>* </span>this</span>.</span>quantity</span>;
</span>  }
</span>
</span>  @</span>action </span>setQuantity</span>(</span>quantity</span>) {
</span>    </span>this</span>.</span>quantity </span>= </span>quantity</span>;
</span>  }
</span>}
</span>
</span>const </span>row </span>= new </span>TableRow</span>(</span>10</span>);
</span>console</span>.</span>log</span>(</span>row</span>.</span>total</span>);
</span>row</span>.</span>setQuantity</span>(</span>10</span>);
</span>// Only computed on the call
</span>console</span>.</span>log</span>(</span>row</span>.</span>total</span>);
</span>// Not recomputed if the observables used didn't change
</span>console</span>.</span>log</span>(</span>row</span>.</span>total</span>);
</span>
</span>// Use `useStrict` to force state to only be modified in `action` fns
</span>row</span>.</span>quantity </span>= </span>10</span>; </span>// will error
</span></code></pre>
We don't use the strict mode ourselves</p>
MobX in real life🔗</a></h2>
Now that you know the basics of MobX, it's time to see how it looks in production.
It's currently the backbone of our frontend app in Proppy so we will use examples from it.</p>
If you are doing SSR, be aware that the way we handle stores shown below will not work for you.</p>
Converting Proppy to use MobX took about 4 days, numerous long-standing issues were fixed along the way and the end result was a deletion of around 1000 to 2000 lines (estimate as we also moved to use npm @types for typings in that branch).</p>
Stores🔗</a></h3>
Our stores are simple singleton classes that have observable properties.
Here's a shorter version of one of our stores, dealing with clients for proposals.</p>
import </span>{ </span>observable</span>, </span>action</span>, </span>map</span>, </span>transaction</span>, </span>ObservableMap </span>} </span>from </span>"mobx"</span>;
</span>
</span>// a class definition with types
</span>import </span>{ </span>Client </span>} </span>from </span>"./models/Client"</span>;
</span>import </span>fetchling </span>from </span>"../utils/fetchling"</span>;
</span>import </span>uiStore </span>from </span>"./UIStore"</span>;
</span>
</span>export </span>class </span>ClientStore </span>{
</span>  @</span>observable clients</span>: </span>ObservableMap</span><</span>Client</span>> </span>= </span>map</span><</span>Client</span>>();
</span>
</span>  </span>getClient</span>(</span>id</span>: </span>number</span>) {
</span>    </span>return </span>this</span>.</span>clients</span>.</span>get</span>(</span>id</span>.</span>toString</span>());
</span>  }
</span>
</span>  @</span>action </span>fetchAll</span>()</span>: </span>Promise</span><</span>any</span>> {
</span>    </span>return </span>fetchling</span>(</span>"/clients"</span>).</span>get</span>().</span>then</span>((</span>response</span>: </span>any</span>) </span>=> </span>{
</span>      </span>transaction</span>(() </span>=> </span>{
</span>        </span>this</span>.</span>setClients</span>(</span>response</span>.</span>clients</span>);
</span>      });
</span>    });
</span>  }
</span>
</span>  @</span>action </span>deleteClient</span>(</span>clientId</span>: </span>number</span>) {
</span>    </span>const </span>client </span>= </span>this</span>.</span>clients</span>.</span>get</span>(</span>clientId</span>.</span>toString</span>());
</span>    </span>return </span>fetchling</span>(</span>`/clients/${</span>clientId</span>}`</span>).</span>delete</span>()
</span>      .</span>then</span>(() </span>=> </span>{
</span>        </span>this</span>.</span>clients</span>.</span>delete</span>(</span>clientId</span>.</span>toString</span>());
</span>        </span>uiStore</span>.</span>notify</span>(</span>`Client deleted`</span>, </span>false</span>);
</span>      })
</span>      .</span>catch</span>(() </span>=> </span>uiStore</span>.</span>notify</span>(</span>`Client ${</span>client</span>.</span>name</span>} could not be deleted. Please try again later`</span>, </span>false</span>));
</span>  }
</span>
</span>  @</span>action </span>updateClient</span>(</span>clientId</span>: </span>number</span>, </span>name</span>: </span>string</span>) {
</span>    </span>return </span>fetchling</span>(</span>`/clients/${</span>clientId</span>}`</span>).</span>put</span>({</span>name</span>})
</span>      .</span>then</span>((</span>response</span>: </span>any</span>) </span>=> </span>{
</span>        </span>this</span>.</span>clients</span>.</span>set</span>(</span>clientId</span>.</span>toString</span>(), </span>new </span>Client</span>(</span>response</span>.</span>client</span>));
</span>        </span>uiStore</span>.</span>notify</span>(</span>`Client updated`</span>, </span>false</span>);
</span>      })
</span>      .</span>catch</span>(</span>response </span>=> </span>{
</span>        </span>uiStore</span>.</span>notify</span>(</span>`Client could not be updated. Please try again later`</span>, </span>true</span>);
</span>        </span>if </span>(</span>response</span>.</span>errors</span>) {
</span>          </span>return </span>response</span>.</span>errors</span>.</span>errors</span>;
</span>        }
</span>      });
</span>  }
</span>}
</span>
</span>const </span>clientStore </span>= new </span>ClientStore</span>();
</span>export default </span>clientStore</span>;
</span></code></pre>
Quite simple stuff.
You can see we are calling another store from our store. That would be a big no-no in Redux and we were using a middleware to solve that previously.
It feels much nicer now: we have a full view of what's happening and it's very easy to see if something is missing (which was actually the case for some ajax requests).</p>
This example doesn't really show it but every data stored in a store is typed and trying to access client.random</code> would be a compiler error.
It really shines for complex objects like cost tables that were previously a simple map with no schema and are now fully typed objects with functions of their own. Thanks to that, we moved things such as calculating totals to the cost table class rather than a React component like before.</p>
Components🔗</a></h3>
We're using the mobx-react</code> package that gives us the observer</code> decorator that we put on top of a component.
Doing so gives us the same thing as the autorun</code> in the MobX by example section: when an observable used in the render</code> function changes, the component will be re-rendered.
@observer</code> also comes with an optimized shouldComponentUpdate</code> that works very well in our experience: the only shouldComponentUpdate</code> left in our code are the ones impossible to not handle manually due to contenteditable</code>.</p>
Since we don't do server side rendering, we can directly import a store and call its function directly. Here's a slightly modified code sample for the Settings>Clients page:</p>
import </span>* </span>as </span>React  </span>from </span>"react"</span>;
</span>import </span>{ </span>observer </span>} </span>from </span>"mobx-react"</span>;
</span>import </span>{ </span>observable </span>} </span>from </span>"mobx"</span>;
</span>
</span>import </span>companyStore </span>from </span>"../../stores/CompanyStore"</span>;
</span>import </span>clientStore </span>from </span>"../../stores/ClientStore"</span>;
</span>// ... some component import
</span>
</span>@</span>observer
</span>export </span>class </span>Clients </span>extends </span>React</span>.</span>Component</span><{}, {}> {
</span>  </span>// not used, only here for the sake of example
</span>  @</span>observable clientAdded</span>: </span>boolean </span>= </span>false</span>;
</span>
</span>  </span>// Our async loaded component will call that function and wait until
</span>  </span>// the promises complete to render that component
</span>  </span>static </span>fetchData</span>() {
</span>    </span>return </span>Promise</span>.</span>all</span>([
</span>      </span>companyStore</span>.</span>fetchUs</span>(),
</span>      </span>clientStore</span>.</span>fetchAll</span>(),
</span>    ]);
</span>  }
</span>
</span>  </span>renderClients</span>() {
</span>    </span>return </span>clientStore</span>.</span>clients</span>.</span>values</span>().</span>map</span>(</span>client </span>=> </span>{
</span>      </span>return </span>(
</span>        </span><</span>div className</span>=</span>"client" </span>key</span>=</span>{</span>client</span>.</span>id</span>}>
</span>          <</span>span onClick</span>=</span>{() </span>=> </span>clientStore</span>.deleteClient(</span>client</span>.</span>id</span>)} </span>className</span>=</span>"icon-delete" </span>/>
</span>          <</span>InlineInput
</span>            </span>value</span>=</span>{</span>client</span>.</span>name</span>}
</span>            </span>onEnter</span>=</span>{(</span>value</span>) </span>=> </span>clientStore</span>.updateClient(</span>client</span>.</span>id</span>, </span>value</span>)} />
</span>        </</span>div</span>>
</span>      );
</span>    });
</span>  }
</span>
</span>  </span>renderForm</span>() {
</span>    </span>return </span>(
</span>      </span><</span>InAppForm
</span>        </span>inline</span>=</span>{</span>true</span>}
</span>        </span>resetOnSuccess
</span>        </span>submitText</span>=</span>"Add client"
</span>        </span>onSubmit</span>=</span>{(</span>data</span>) </span>=> </span>clientStore</span>.createClient(</span>data</span>)} />
</span>    );
</span>  }
</span>  </span>render</span>() {
</span>    </span>return </span>(
</span>      </span><</span>SettingsContainer</span>>
</span>        <</span>div className</span>=</span>"clients"</span>>
</span>          <</span>h2</span>>Manage {</span>your</span>} clients</</span>h2</span>>
</span>          {</span>this</span>.renderForm()}
</span>          <</span>div className</span>=</span>"clients-list"</span>>
</span>            {</span>this</span>.renderClients()}
</span>          </</span>div</span>>
</span>        </</span>div</span>>
</span>      </</span>SettingsContainer</span>>
</span>    );
</span>  }
</span>}
</span></code></pre>
No ceremony needed, everything works out of the box as if I was just dealing with plain JavaScript objects. All the store functions and data are typed too. Trying to call clientStore.deleteClient("1")</code> for example would be a compilation error and I only had to write the type once: in the store as shown before.</p>
Another aspect not mentioned before is that you can also use observable</code> to remove the need for React state.</p>
Rather than having a state and updating it with this.setState</code>, you can just update your variable directly and it will re-render the component if that property is used in the render method.
To use the previous example, if I wanted to display a banner after adding a client in that component I could set this.client = true</code> and render something different when this.client</code> is true. No more this.setState({..} as any)</code> to satisfy the TypeScript compiler.
Another neat thing about using MobX for state is that changes will be logged if you are using dev tools.</p>
Dev tools🔗</a></h3>
For React, mobx-react-devtools</code> is available and is pretty great. See the gif below from its repo to have an overview of the 3 features.</p>

    
        
    </a>
</div>
I have mostly used the logging to inspect action and state changes while debugging and to spot erroneous updates and the re-rendering highlighter to figure out if some of our components were re-rendering too often.</p>
Useful links🔗</a></h2>

Official docs</a> and in particular Common pitfalls & best practices</a> and What does MobX reacts to?</a></li>
In-depth explanation of MobX</a></li>
Understanding MobX and when to use it</a></li>
Example: real-life with router/ajax etc</a></li>
</ul>
Conclusion🔗</a></h2>
Overall, we are very happy with the transition to MobX and would recommend investigating it if you are looking for a state management solution, especially if you are using TypeScript or Flow.
I'm pretty impressed by the constant work the TypeScript team has accomplished and highly recommend it as well if you are planning to stay on the JavaScript side and not go for Elm/PureScript/etc.</p>


Where to incorporate if you are a EU citizen
Unknown — Sun, 10 Jul 2016 00:00:00 +0000
We are very lucky as EU citizens to have access to 28 (well, soon 27 apparently) countries.
To give a bit of context to this blog post, We Are Wizards is currently a company based in the UK, founded by 2 French and one German, all living in London at the moment.</p>
While this post tries to be general, it is guided by our own requirements. There might be inaccuracies in this article so don't take my word for it and contact companies/government in the countries before making a decision if you decide to do so. We've added the tax rates so you can get a feel of the different options but they are not a deciding factor for us.</p>
Our requirements🔗</a></h2>
As mentioned in the introduction, we are French and German and the only common language is English so being able to do all (or at least the vast majority) government/bank interactions in English is a hard requirement.</p>
We also need to be able to incorporate in a country without living there since we don't want to move or, in my case, want to travel. This is especially true if you are planning to be a digital nomad.</p>
Lastly, we want a business-friendly country with a good record on privacy and surveillance law as we run Passopolis</a>, an open-source password manager that relies on end-to-end encryption.</p>
To sum it up, our requirements are:</p>

we need to be able to do things in English</li>
we need to be able to incorporate without living there</li>
we want its government to be privacy friendly and not authoritarian</li>
</ul>
Your own requirements will obviously differ and some countries that we disregard in the next section might be the perfect fit for you. Or you might want to get out of the EU to not deal with VAT MOSS</a> like Ghost</a> for example.</p>
Countries selection🔗</a></h2>
France, Germany, Spain, Portugal, the Netherlands and Denmark fail as I couldn't find all the needed information on incorporation in English which means that the local language is required for all interactions.</p>
The USA (via Stripe Atlas</a>) also doesn't make much sense from a EU citizen point of view as we have access to better choices as we will see in a moment and opens you to their patent laws.
This might be different if you are planning to raise money in the US though but I don't know anything about that.</p>
With the rejected countries out of the way, let's go over the potential choices I have identified after a bit of research.</p>
To keep the each country information DRY (Don't Repeat Yourself), one advice common to every country including your own is to get an accountant from the start as they are not that expensive in the grand scheme of things and they make everything easier.</p>
Do note that you can Google "company formation country_X" and you will get lots of companies offering services helping you with incorporation and taxes.</p>
United Kingdom🔗</a></h3>
Trivia🔗</a></h4>
The UK is very business friendly and the biggest tech centre in Europe. You can probably go to a tech meetup every day if you wanted to and you get to meet and work with people from all over the world.</p>
In terms of privacy laws, the UK is not doing too great with the IP Bill</a> it's trying to pass.</p>
The obvious elephant in the room is Brexit</strong>. No one really knows when it will actually happen and what will be the outcome so there is a great deal of uncertainty about, well, everything.
The biggest uncertainty for us is our residency status as we are not UK citizens and there is a greater than zero risk that we would not be able to stay. Getting citizenship is not an option for me for example as I'm moving out of the country soon.</p>
Sadly enough, EU VAT handling could become even harder than the current VAT MOSS for UK businesses</a>.</p>
The UK is currently the place to be in Europe if you want to get investment but it might change after Brexit.</p>
Taxes🔗</a></h4>
The corporation tax is currently 20%</strong> but there are talks to reduce it to 17% by 2020</a> and potentially even further.</p>
Dividend tax</a> depends on your total income and can vary quite a bit.</p>
How to incorporate/open bank account🔗</a></h4>
Incorporating is very simple and usually only takes a day or so. Most accountants will offer incorporation as a freebie.
You can open a bank account remotely and most banks in the UK (at least the one I've seen) offer a good online banking experience.</p>
With an accountant and a tool like FreeAgent or Xero, you don't really need to do any significant business administration work. We haven't run into issues with HMRC (the revenue service in the UK) that you are dealing with as a company but I have heard many horror stories about it.</p>
Virtual offices are easy to find in London so you don't have to live in the country.</p>
Ireland🔗</a></h3>
Trivia🔗</a></h4>
The other obvious choice when it comes to English speaking countries in the EU. It is also famous for being the main place for big companies to do tax avoidance with a special arrangement called the Double Irish arrangement</a>.</p>
Ireland is very business friendly, doesn't seem to want to ban encryption any time soon and its culture is similar to the one in the UK.</p>
Unfortunately, politics there seem partially driven by religion and they have actually introduced a blasphemy law</a> in 2009, which seems hard to believe.</p>
Taxes🔗</a></h4>
The corporation tax is 12.5%</strong> and it might get interesting if the UK and Ireland get into a lower corporation tax war. The dividend tax rate is a flat 20%</strong>.</p>
There is also a tax exemption for the first three years</strong> if the company's corporation tax to pay does not exceed €40,000, which corresponds to €320,000 of profit at the 12.5% tax rate. In short, unless you're growing super fast in terms of profit, you're not paying any corporation tax for the first three years.</p>
How to incorporate/open bank account🔗</a></h4>
Incorporating in Ireland takes 2-3 days and cost €320 euros. Opening a bank account might be possible remotely but it might be easier to do a day trip to Dublin.</p>
Virtual offices are easy to find in Dublin so you don't have to live in the country.</p>
Estonia🔗</a></h3>
Trivia🔗</a></h4>
I'll be the first one to say I don't know much about Estonia. According to Enterprise Estonia</a>, most of the interactions with the government and banks can be done in English. Having a local partner is useful for the more complex cases where it might be needed and, since you should get a local accountant, this shouldn't be an issue.</p>
The political environment seems pretty quiet and the current leading political party, the Estonia Reform Party</a> is advocating for even more liberalism when it comes to companies.</p>
Estonia ranks 1st on the Barclays Digital Development index and 16th on the Doing Business ranking</a></p>
Do note that Stripe is not available in Estonia yet so it might be a deal breaker if your business depends on it, which might be our case depending on what payment provider we choose for Proppy(article on that coming soon). There is no timeline for it as well:</p>
@WeAreWizardsIO</a> No timeline as of yet, sorry! Feel free to sign up here and we'll notify you as soon as we're ready https://t.co/vbuzSSxceJ</a></p>— Stripe (@stripe) 25 July 2016</a></blockquote>
Vincent Prouillet: Developer & Entrepreneur

Releasing Zola 0.12

Using CSS modules with Sass, Webpack and TypeScript

Tera v1 is here!

Setting up a React+TypeScript frontend with Webpack — Part 2

Setting up a React+TypeScript frontend with Webpack — Part 1

Storing secrets in a git repository with git-crypt

Managing environment variables with direnv

Zola 0.6.0: start of multi-lingual sites

Gutenberg is out, Zola 0.5.0 is in

Atomic Design in Single Page Applications

Organisms🔗</a></h3> As with molecules, there are two types of organisms I distinguish here:</p> components using one or more molecules</li>

An overview of package management in Python in 2018

Gutenberg 0.4.0: custom taxonomies, image processing and more

Updating the templates🔗</a></h4> We need to change two things regarding the taxonomies templates:</p> their location</li>

Tera 0.11 is released

Gutenberg 0.1.3: themes are in

Releasing Gutenberg 0.1.0

A different approach to routing in Single-Page Applications: now in production

A different approach to routing in Single-Page Applications

This month in my Rust projects

Announcing Gutenberg, a static site engine

My current frontend setup is pretty neat

Releasing Tera 0.6 and thoughts on a validation crate

Handling errors in Rust

Releasing Tera 0.4 and state of my other crates

jsonwebtoken (1.1.5)🔗</a></h3> Strongly typed JWT library. I like the current API but a few more features are planned for 2.0:</p> moving to Serde from rustc-serialize</li>

A MobX introduction and case study

Where to incorporate if you are a EU citizen
