Forem: JeB

Open Source Series: Documentation

JeB — Sun, 16 Feb 2020 18:14:56 +0000

or answering the what and how questions

Hello and welcome to the third part of the “Open Source” journey.
For those of you who haven’t read the previous parts or wonder what is the planned content for the next parts:

Table of content

Intro
Starting a Project
Documentation
Publicity (WIP)
Issues and PRs (WIP)
Automation (WIP)
Versions management (WIP)

Recap

In the previous parts we’ve discussed what Open Source is and how one can start a new open source project.
The first two parts were targeted to those who consider creating an open source project, to let them know what to expect and give them some headstart in the open source world.

This part, as well as the coming ones, will also be relevant to the people who already maintain an open source project and help them improve at what they do.

The baseline for this part:

You already have an open source project, it is available on Github and it can be consumed easily via one of the package registries.

*** If you have no idea what I’m talking about I suggest you to read the first two parts.

So here we go

An open source project without documentation is a dead project

It is dead because no one will dive into your code to find out how it should be used. And even before how, no one even knows what your code is supposed to do.

So these are basically the two things that your documentation should contain — what and how. These are the corner stones, the must-haves of documentation.

Description

Description is the first thing everyone sees upon entering a Github repository. Therefore a good description should answer in a short and informative manner to the what question. For example:

React:

A declarative, efficient, and flexible JavaScript library for building user interfaces. https://reactjs.org

Moment.js:

Parse, validate, manipulate, and display dates in javascript. http://momentjs.com

Angular builders (this one is mine):

Angular build facade extensions (Jest and custom webpack configuration)

The description can be edited by clicking on the Edit button at the top right of your repository:

README.MD

README.MD is a file in the root directory of your project written with Markdown syntax, which contains all the information one needs to know about your project.

The README file should contain a detailed description (which expands on the what question) and very detailed instructions on how to use you project.
The instructions should cover every single piece of public API, preferably with usage examples.

A few points for writing a good API documentation:

Keep it simple
The simpler the API and the example — the easier for a user to understand what it does on how to use it
Keep it structured
Use the same template and visual structure for every API method, this way you’ll define your own language for communicating the API to the user.
Be a user
Always write API description from the users perspective. Assume that you know nothing about the internals and this documentation is all you have.
Keep it up to date
As your project evolves the APIs might change. Make sure that your README file always contains the most actual APIs and examples

The README can (but doesn’t have to) contain the following things:

Link to a contribution guide
List of contributors
Link to a change log
Latest version
License
Build status
Downloads counter
Link to a chat for fast feedback

Badges

Badges are a fairly good way to visually expose the essential info about your project, such as: build status, version, license and various tools used by your project.
There are quite a few options but I’d recommend you use shields.io badges.
They have a badge for literally everything.

Adding a badge to your README file is really simple:

Go to shields.io
Choose the appropriate category
Click on a badge you’d like to add to your README
Fill in the required information (if any)
Choose Copy Markdown from a drop down menu
Paste the markdown into your README file

The badges are usually put at the top of the README file right before the detailed description. This is what it looks like:

Tests

API reference is great, but nothing compares to a real code using your public APIs.
One of the best ways to complement your documentation is having a good code coverage with descriptive tests. Sometimes tests explain the code better than any documentation.

Wrapping it up

In this part we’ve only covered the basics of documentation. It has a lot more than just a README or a description, for example, as your project grows and issues arise, they become an integral part of the documentation.

However, having a README file that covers the public API is the bare minimum for any decent open source project

Thanks for reading, make sure you follow me here or on Twitter if you don’t want to miss the next part in which we’re going to talk about Publicity.

Open Source Series: Starting a Project

JeB — Wed, 22 Jan 2020 20:44:57 +0000

or how to open your project to the world

Hello and welcome to the second part of the “Open Source” journey. For those of you who haven’t read the first part or wonder what is the planned content for the next parts:

Table of content

Intro
Starting a project
Documentation
Spreading the word (WIP)
Getting collaborators (WIP)
Issues and PRs (WIP)
Automation (WIP)
Versions management (WIP)

Recap

In the previous part we’ve discussed what is Open Source and why anyone would bother with that. In this part we’re going to get more practical and we’ll discuss how one actually starts an open source project.

So you’re in scenario #1, you have a solution for a specific problem and you’re eager to share it with the world. Let’s emphasize it again:

It’s not about your ego
You’re not hoping to benefit from it
You truly want to help others with the same problem

If you answered yes to all of these then here is a quick checklist for you to make sure you’re doing the right thing:

Make sure that open source is the right format. If it’s something small that you want to share with the world then a small blog post might be just enough.
Double check that a similar project doesn’t exist already. Maybe your solution makes a perfect PR for an established open source project.

Be prepared for what’s coming

As I mentioned, owning an open source project carries a lot of difficulties.

One difficulty that stands out is that it requires a lot of your time. Everything that you do for your open source requires time, whether it’s writing code, managing issues, updating dependencies, talking to people, answering questions and etc. Every minute that you invest into your open source is a minute that you could have but didn’t invest in your family, your hobby, your health and what not.

The only thing that you can do about it is delegation.
When (or should I say “if”) you have enough collaborators you can outsource part of your responsibilities to the people you trust.

Code separation

So here we go, you have a solution for your specific problem and you think others can benefit from that. It is still integrated within your code base and you probably don’t want to make the whole code base an open source (unless you do).

First you have to separate this code from the rest of your code base.

Start with refactoring

…which will eventually cause all the code that is going to be opened to reside in a separate directory.

Make it generic

Make sure that the code in the new directory is generic and is not bound to your specific problem, make an abstraction layer if needed.

As an example I started angular-builders with a very specific need (coming from one of my other open source projects) of adding custom loader for native modules to Angular build.
I could have created native-module-builder which would serve solely this very purpose. However, I realized that at a relatively low cost I can create a more generic solution that would solve similar (but not the same!) problems.

This is how custom-webpack builder was born.

Keep it simple

Generic is great but be careful not to get too excited about that.

Premature optimization and over-generalization are two very well known problems in software engineering. You should find this sweet spot where your solution solves problems other than yours but not all the problems in the world.

If you build a scale where the solution for your specific problem is 1 and a solution for all the world problems is 100 then you should start with 2.

Your generic code should be able to solve a a few more problems than your specific code.

Eat your own dog food

Keep using this generic code in your code base at every step — doing so makes sure you eliminate the unnecessary parts and leave only what’s needed. It also ensures that the code you’re going to open is working properly.

Remember, you are the very first user of your open source project.

Don’t get sued

If you’re extracting the code from your company code base consult with your superiors and if needed with the legal department. Make sure that they support your initiative and that the code you’re going to open is not subject to the IP (intellectual property) of your company. This will also help you to decide which open source license is more suitable for your project.

When everything is working, the code is separated and is generic enough, you have all the approvals (if needed) - it is time to open it to the world.

Opening the project to the world

Once your open source code is separated and generalized it’s time to disconnect it completely from your code base.

Going public

First, you have to open the source code of your project (at the end of the day that what makes it an Open Source Project!).
There are different options for hosting source code online but we’ll go with the default — Github.

Create a new repo on Github
Clone the repository
Move the sources from the directory you previously created (don’t remove the directory yet).
Commit & push — voila it’s now an open source project.

Or is it?

Creating a package

Your project is publicly available, but no one is using it (including you, since you’re using a copy of this code within your larger code base), and no one is aware of its existence.

Furthermore the only format in which your project is publicly available on the web is the source code, and the only way to consume it is copy-pasting the code into ones code base. Not a very convenient way, don’t you think?

In order to properly distribute your project you have to:

Create a package out of the source code
Make this package available on one of the public package registries (depends on your ecosystem, for example, for Java it might be Maven Central Repository, in the case of JavaScript it might be Npm Package Registry and etc.)

This is when you add a build chain to your new shiny repository, define project name etc.

I’m not going to break down the whole process because it is very dependent on your ecosystem, set of tools and language you are using.

You might be an all around person to whom defining a new project as well as adding a build chain and publishing the package is a piece of cake.
If this is the case — good for you!

You also might be a person that is used to only write code but never faced all these definitions, configurations, artifacts and stuff like that. It might be a whole new world to you.
Well, time to learn. Not going to be quick, I promise you that.

In any case

When you’re done with filling all the missing puzzle pieces in your head, you’ve learned everything about the relevant package registry and your package is actually published, then and only then can you truly consider your project open source.

At this point you can actually tell people: “Hey, I already have a solution to your problem, just add this package to your project and use it!”

Sanity check

Before your project goes viral you better make sure it works.

A sanity check for your package would be actually removing the generic directory from your larger code base and use the publicly available package instead.
After all, you’re the very first user of your open source project.

Further development

When you start using the package in your code base the development flow is likely to change: previously the now-open-source-code has been a part of your code base; you could consume the changes right away but now it’s as much of an external package as any other 3rd party package used in your code.

Thus, when you develop a new feature in your shiny new open source project you’ll have to publish it first in order to be able to consume it in your larger code base. However you cannot publish it if you aren’t positive it works, because once published it might affect other users.

So here are a few things you can do in order to avoid publishing broken versions:

Cover your code with tests, both unit tests and end-to-end tests. I don’t think I have to convince you how important the tests are.
Package and install the new version of the package locally, into your larger code base. Once verified that everything works as expected you may publish it.
Publish a beta version which is available only for those who explicitly want it rather than to the whole world. For example in npm package registry there are dist tags that can be used for this purpose. The default tag is latest and when you run npm install mypackage it effectively runs npm install mypackage@latest. When you publish a new version under another tag, for instance beta, one will have to explicitly install from this tag in order to get the latest version: npm install mypackage@beta.

Wrapping it up

Unlike the previous part, which was completely theoretical, this part actually requires some work from you. Depending on your experience and learning abilities it might take you a few days or even weeks to complete this mandatory step. And we didn’t even start yet.
This is why it is my duty to ask you again:

Are you really prepared to give a decent amount of your precious time to the community?

Thanks for reading, make sure you follow me here or on Twitter if you don’t want to miss the next part in which we’re going to talk about Documentation.

Owning an Open Source Project: Part 1

JeB — Sun, 05 Jan 2020 14:59:36 +0000

Intro or where the journey begins

Have you ever thought of having your own open source project?
I bet you have — you’re reading this article. Maybe you are thinking about it right now. Maybe you came here to better know what to expect, what challenges you’re going to face and how to deal with them.
Well, you’ve come to the right place.

In the following series of articles I’m going to share my personal experience in owning an open source project. Owning. Not contributing to an open source project but owning one. There is a big difference and in this series we’re going to learn why.

Table of content

Intro or where the journey begins
Starting an open source project
Documentation
Spreading the word (WIP)
Getting collaborators (WIP)
Managing issues and pull requests (WIP)
Automation (WIP)
Breaking changes and back-ports (WIP)

Who I am

My name is JeB and I’ve been maintaining a few open source projects for a couple of years. The most popular one and the one from which I’ve learnt the most is @angular-builders. At the moment of writing this article it has ~600 stars on Github and about 400k monthly downloads.

Yes, it’s not even close to huge projects like Angular or React but I feel that I have enough experience to share with you in order to help you avoid the same mistakes I did and more important — to understand the cost of owning an open source project.

So what is open source?

Let’s first establish a common language and align on key terms and definitions.
What is open source? Here is a very generic definition from a well known Open Source Encyclopedia (aka Wikipedia):

Open source is the concept of the information allowing the replication or modification of something being open to the public.

or, in terms of software development models:

The open-source model is a decentralized software development model that encourages open collaboration.

A main principle of open-source software development is peer production, with products such as source code, blueprints, and documentation freely available to the public.

In the case of Wiki we have those who edit the articles (contributors) and those who approve the edits (more experienced members, moderators). If we project it onto the software world the editors would form a core team of an open source project and the contributors would be, well, contributors.

Wikipedia is a huge open source project but it has all started from something small. Wikipedia was born from Nupedia and it was born for a reason:

Despite its mailing list of interested editors, and the presence of a full-time editor-in-chief, Larry Sanger, a graduate philosophy student hired by Wales, the writing of content for Nupedia was extremely slow, with only 12 articles written during the first year.

So here’s where the first question comes:

Why bothering with open source

As you can imagine from the previously read one of the main reasons for opening something to the wider audience is to gain collaborators.

Together we’re strong

(Zarya, 2016)

At the moment of writing this article Wikipedia has 37,899,499 registered accounts of which 134,022 are actively editing.

Just think of it… 134,022 active collaborators. Oh, and it has 6M content pages!

Would the numbers have been the same if Nupedia didn’t move to open source model? I highly doubt it.

Nothing is different when it comes to the software. In order to solve a certain problem you have to write code. In order to solve a big problem you have to write a lot of code. In order to solve it properly you have to write high quality code, make a high quality design etc. All this requires resources, which, let’s be honest, you don’t have. You have a rent to pay after all.

While gaining collaborators is a reasonable incentive, almost no one starts a new open source project solely because of it.
Obviously the reasons might be different but let’s talk about most popular ones.

Careful what you wish for

A few scenarios that come across my mind are:

You face a problem, there is nothing out there that solves it for you (or there is something but it costs money) so you have to solve it yourself, you manage to solve it, you’re really excited about your work and you think others can benefit from it.
You want to be recognized as founder of an open source project, you want this fancy line in your CV, you have an ego (we’re all human after all). If this is the main reason for you then I promise you, after reading this series you’ll reconsider — it’s not worth it.
You face a problem, there is an open source project that actually solves it for you but it’s not good enough (in your opinion) or doesn’t have the exact feature you need. If you create a new open source project solely because of this then most probably you’re at #2 (ego). Make yourself a contributor, create a PR to the existing project instead.
If the existing project has a different vision and making a PR is not an option you should consider either extending it by reusing its functionality in your project or forking it. It may save you a lot of headache later.
You face a problem, there is nothing out there that solves it for you and you think that starting the solution as open source from the very beginning is a very good idea.
It’s not.
Solve the problem, make sure it works for you and after that go to #1.

These are the 4 incentives I find most popular for creating a new open source project but in this series we’re going to focus mainly on scenario #1.

The reason is simple — I believe that if the main reason for starting an open source project is other than eagerness to share and contribute then this won’t hold.
For quite a long time the fact that you’re helping someone might be the only reward you get. And if this is not the kind of satisfaction you’re looking for then maybe you should stop here and not waste your time.

There is another quite popular scenario which is worth to mention.
There are companies that open part of their code to the community.
For example, Angular (maintained by Google), React (maintained by Facebook), VSCode (maintained by Microsoft) and more.
The reasons for them to do that may vary but gaining collaborators and contributing to community are surely among them.
While I can’t argue with the importance of this practice, this scenario is quite different from the others because employees that maintain such projects get paid for their job.
If you work at a company that considers the possibility of creating an open source project, the majority of the content here will be still relevant for you, however the incentives might be different.

Wrapping it up

If I had to summarize this part in one sentence it would be:

Make sure your intentions match your expectations

Believing that you want to have an open source project is not the same as actually having one, as you will see in the following articles.

Thanks for reading, make sure you follow me here or on Twitter if you don’t want to miss the next part in which we’re going to talk about actually Starting an open source project.

Angular 6: “ng test” with Jest in 3 minutes

JeB — Tue, 21 Aug 2018 11:55:42 +0000

Hey folks.

Today I’m going to show you how to setup your Angular CLI workspace to work with Jest while keeping it clear of boilerplate code.

I'm not going to explain why you should choose Jest over Karma, assuming you already did that choice, however I will give you a link to an article that explains the reasons.

So let’s get started!

Setting up Jest

Remove Karma related stuff:

npm remove karma karma-chrome-launcher karma-coverage-istanbul-reporter karma-jasmine karma-jasmine-html-reporter
rm src/karma.conf.js src/test.ts

Install @angular-builders/jest and `jest`:

npm i -D jest @angular-builders/jest

Update your Typescript configurations:

Although you run your unit tests with Jest, Protractor (e2e tests) still has to use Jasmine. Due to this fact it’s possible that you favorite IDE will get confused with the typings and will propose you Jasmine types in unit tests or Jest types in e2e test. In order to avoid that kind of problems you have to specify the types explicitly:

In tsconfig.spec.json (src directory or project roots, used by Jest):

"compilerOptions": {
 ...
 "module": "commonjs",
 "types": ["jest"]
}

In tsconfig.json (root directory, used by IDE):

"compilerOptions": {
    ...
    "types": ["jest"]
}

In angular.json change `@angular-devkit/build-angular:karma` to `@angular-builders/jest:run`:

"projects": {
    ...
    "[your-project]": {
         ...
         "architect": {
                ...
                "test": {
                          "builder": "@angular-builders/jest:run"
                          "options": {
                                ...// see below
                          }

Detailed description of options object can be found here.

This is it, now you can run your tests with Jest.

Running the tests with Jest

To run tests for all the projects in workspace: ng test
To run tests for a specific project my-project: ng test my-project
You can specify Jest CLI options either in builder options (useful when it is a persistent config) or right to ng test as a parameter (useful when it is a one-timer). For example to run a single test: ng test --testNamePattern="My test suite My test case"

Angular CLI 6 under the hood - builders demystified

JeB — Tue, 07 Aug 2018 15:43:44 +0000

Update:

The article is relevant up to Angular 7.2.x.
In 7.3.0 this API has been deprecated (yet supported) and in 8.0.0 it will be replaced with the new API.
The updated article is yet to come.

Hey folks. Hope the sun is shining for you today.

In the previous article we talked about customizing Angular 6 build configuration without ejecting the underlying webpack configuration.

The proposed solution was to use an existing custom builder.

Today we’ll take a look under the hood and create our own custom builder from scratch.

Angular CLI builders

Angular CLI 6 came with a new architecture, basically a rewrite of the old CLI, which was broken down into small pieces.

In fact, Angular CLI itself has nothing to do with the configuration you provide in angular.json, not anymore. Instead, it wraps Angular Dev Kit and triggers architect targets.

Briefly speaking:

Angular CLI package contains pre-defined commands, help and CLI related stuff.
Architect package handles the configuration from angular.json. It is responsible for mapping the architect target into the relevant builder, create the builder and trigger it with the configuration specified in angular.json for this builder.
Builders are the ones who do the actual job. Thus,BrowserBuilder runs webpack build for browser target, KarmaBuilder starts the Karma server and runs webpack build for unit tests and so on.

Angular CLI commands and architect targets

When you run ng build or ng test or any of the predefined Angular CLI commands a few things happen:

Angular CLI command is transformed into a relevant architect target
A relevant builder is created
A relevant builder is triggered with the relevant configuration

When you run a custom architect target, the following happens:

A relevant builder is created
A relevant builder is triggered with the relevant configuration

As you can see the only difference between the predefined command and custom architect target is that in the latter there is no mapping from the Angular CLI command to an architect target.

In a nutshell there is one generic command ng run , that receives an architect target as an argument (in format project:target ) and asks the architect to execute this command.

Thus, each one of the predefined Angular CLI commands that are mapped to an architect target can be executed with ng run. E.g:

ng build: ng run my-cool-project:build
ng test : ng run my-cool-project:test

And so on…

The beauty is that once you’ve created your own builder you can put it in any architect target you want:

You can create your own target, call it my-target and execute it with
ng run my-cool-project:my-target

You can replace the builder in one of the existing targets (say, build target) and execute it with the predefined Angular CLI command ( ng build ), because as we’ve seen, Angular CLI commands are just mappings into relevant architect targets.

Architect targets configuration

Let’s take a closer look on angular.json file:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "example": {
      "root": "",
      "sourceRoot": "src",
      "projectType": "application",
      "prefix": "app",
      "schematics": {},
      "architect": {
        "build": {
            ...
        },
        "serve": {
            ...
        },
      }          
    }
  }
}

Inside each project there is an entry called architect and it contains architect targets configurations. Thus, in this particular example we have only one project called example which, in turn, has two architect targets: build and serve.
If you wanted to add another architect target called, say, format , the file would become:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "example": {
      "root": "",
      "sourceRoot": "src",
      "projectType": "application",
      "prefix": "app",
      "schematics": {},
      "architect": {
        "build": {
            ...
        },
        "serve": {
            ...
        },            
        "format": {
            ...
        }
      }
    }
  }
}

Every architect target configuration has 3 properties:

builder — path to the builder. The format of the path is [package-path]:[builder-name], where [package-path] is a path to a folder with package.json containing builders entry and [builder-name] is one of the entries in builders.json (we’ll return to this later)
options — the configuration of the builder. Must match the builder configuration schema, otherwise the command will fail.
configurations — a map of alternative target options (prod, dev etc.). This is an optional property.

That’s pretty much it for the theoretical background.

Enough talk, let’s do something real!

Creating you own builder

I’m not a fan of doing things in vain, so I had to come up with something more than just Hello World Builder, yet as simple as Hello World Builder.

So imagine you want to display the date and the time on which your application was built last time. The system is loading up, fetching some file that contains the timestamp for the latest build and the date is displayed in the page footer.

What we’re going to do is implement a builder that creates this timestamp file.

Creating the package

A single package can contain multiple builders but in our case it will contain only one.

First thing after you’ve created a folder for your builders package is adding package.json into this folder (architect assumes that builders package is an npm package).
This package.json is just a plain package.json file with one additional entry:

"builders": "builders.json"

Spoiler: the file doesn’t have to be builders.json, can be any name you choose.

builders.json

builders.json is a file that describes your builders. It’s a json file that
follows Angular builders schema and has the following structure:

{
  "$schema": "@angular-devkit/architect/src/builders-schema.json",
  "builders": {
    "builder-name": {
      "class": "path-to-builder-class",
      "schema": "path-to-builder-schema",
      "description": "builder-description"
    },
    ... more builders definitions
  }
}

Single builders.json can contain definitions for multiple builders.

Builder definition

Each builder is defined by two properties:

class — path to Javascript class that implements Builder interface. Architect will parse the configuration and create an instance of this class. You can find the definition of the interface here.
schema — path to json schema that defines builder configuration ( options property in architect target definition). Architect verifies the configuration against this schema and if the configuration is wrong it will fail the target.

Here what our builders.json will look like:

{
  "$schema": "@angular-devkit/architect/src/builders-schema.json",
  "builders": {
    "file": {
      "class": "./timestamp.builder.js",
      "schema": "./schema.json",
      "description": "Builder that creates timestamp"
    }
  }
}

schema.json

Let’s say we want to allow the user to modify the format of the timestamp and the name of the file to which the timestamp will be saved.

Thus, our schema.json will look like this:

{
  "id": "TimestampBuilderSchema",
  "title": "Timestamp builder",
  "description": "Timestamp builder options",
  "properties": {
    "format": {
      "type": "string",
      "description": "Timestamp format",
      "default": "dd/mm/yyyy"
    },
    "path": {
      "type": "string",
      "description": "Path to the timestamp file",
      "default": "./timestamp"
    }
  }
}

If the user hasn’t specified any options in the architect target configuration, architect will pick up the defaults from the schema.

Installing dependencies

To format the Date we will use dateformat package, let’s install it:

npm i dateformat

We’re going to develop our builder with Typescript (though it’s not mandatory) so we have to install it too.
We will also seize the functionality of @angular-devkit/core as well as some of the interfaces from @angular-devkit/architect.
To benefit from Typescript static typing we will probably want to install @types for node and dateformat.

This is it for devDependencies ( @angular-devkit will be used at runtime but rather as a peer dependency). Let’s install them:

npm i -D @angular-devkit/core @angular-devkit/architect @types/node @types/dateformat typescript

The builder

Now we’re ready to implement the builder itself.
First of all let’s define our builder configuration as an interface in schema.d.ts:

Once we have the interface we can implement the generic Builder interface:

run method should return an Observable of BuildEvent that looks like this:

BuildEvent will notify the architect of successful or unsuccessful execution,
and architect, in turn, will pass the execution result to CLI that will
eventually finish the process with appropriate exit value.

In our case we want to return success if the file with the timestamp was
successfully created and failure otherwise:

Let’s break it down:

First of all we get the root (which is the root folder of the host application)
Next we retrieve the path and the format from the options. These should be specified in architect target configuration in angular.json of host application. If none were specified, the default values will be taken from the builder’s schema.
getSystemPath is a utility function that returns system specific path and we concatenate it with the relative path from the options.
We use writeFile function from fs module but since we have to return an Observable and writeFile works with callbacks, we use bindNodeCallback function to transform it into a function that returns Observable.
We format the date with the formatDate function while using the format we’ve got from the options and write the formatted date to the file.
Finally we return success if the file was created successfully and return failure otherwise.

Side node: use the logger to provide build information to the user

Compile the source code to JavaScript and you’re good to go.

Using the builder

Now when the builder is ready you can use it by either specifying a relative
path to the folder in angular.json:

"architect": {
        "timestamp": {
          "builder": "[relative-path-to-package]/timestamp:file",
          "options": {}
        }
}

… or packing it into npm package and installing it locally:

npm pack
cp angular-builders-timestamp-1.0.0.tgz [host-application-root]
cd [host-application-root]
npm i -D angular-builders-timestamp-1.0.0.tgz

angular.json:

"architect": {
        "timestamp": {
          "builder": "@angular-builders/timestamp:file",
          "options": {}
        }
}

… or publishing it on npm and installing from there.

Finishing words

I hope you enjoyed the article and understand the concept better now.
I also hope the sun is still shining and you didn’t spend all the day on this booooooring stuff.

If you’re into open source and have some brilliant idea for a builder that can be useful for everyone, you’re welcome to contribute to angular-builders project.

All the source code of the timestamp builder (as well as the example app that uses this builder) is available on github.

Customizing Angular CLI 6 build - an alternative to ng eject

JeB — Fri, 27 Jul 2018 16:00:53 +0000

So your Angular 6 project just went a bit beyond TODO app and you have to customize your build configuration.
The question is how?

Angular CLI 1.x ng eject VS Angular CLI 6 builders

In Angular CLI 1.x (Angular 5) you had ng eject command for this, which was ejecting the whole underlying webpack configuration and allowing you to modify it as you please.

In Angular CLI 6 this command has been temporarily disabled, and I suspect that it will be deprecated soon due to the new concept called Builders.
With the new Angular CLI you can customize the build process by defining your own builders as well as using one of the builders provided by the community.

Extending underlying webpack configuration

So lets go ahead and customize our build by extending the underlying webpack configuration:

Install @angular-builders/custom-webpack: npm i -D @angular-builders/custom-webpack.
Note that it requires version @angular-devkit/build-angular>=0.7.0 so you might need to install it (if not yet installed):
npm i -D @angular-devkit/build-angular
In angular.json change the @angular-devkit/build-angular:browser builder to @angular-builders/custom-webpack:browser:

    "architect": {
       ...
      "build": {
          "builder": "@angular-builders/custom-webpack:browser"
          "options": {
                ...
          }
      ...
    }

If you build a universal app and would like to modify your server build configuration use @angular-builders/custom-webpack:server instead of @angular-builders/custom-webpack:browser
Add customWebpackConfig to the build target options :

    "architect": {
       ...
      "build": {
          "builder": "@angular-builders/custom-webpack:browser"
          "options": {
                "customWebpackConfig": {
                   "path": "./extra-webpack.config.js"
                }  
                ...
          }
      ...
    }

Check out the full description of customWebpackConfig object here.

Create extra-webpack.config.js in the root of your application (or whatever path you specified in angular.json).
Fill it with extra configuration you need (plain webpack configuration).
Note that in contrary to ng eject this configuration will be merged with the default Angular build configuration so you only have to configure the part you want to change/add. For example, if you want to add another webpack loader, your webpack config will look like this:

    module.exports = {
      module: {
        rules: [
          {
            test: /\.cool$/,
            use: 'cool-loader'
          }
        ]
      }
    };

And what about ng serve?

If you want to run ng serve with custom webpack configuration (given you performed all the above steps) you should do the following:

Install @angular-builders/dev-server
Replace @angular-devkit/build-angular:dev-server inside the serve target with @angular-builders/dev-server:generic
Run ng serve

Additional sources

You can check out this electron-angular-native project for the example of Electron Angular application with node addons built with Angular CLI 6.

What is next

In the next article we will learn how to create your own builder.

Forem: JeB

Open Source Series: Documentation

or answering the what and how questions

Table of content

Recap

The baseline for this part:

You already have an open source project, it is available on Github and it can be consumed easily via one of the package registries.

So here we go

An open source project without documentation is a dead project

Description

README.MD

Badges

Tests

Wrapping it up

However, having a README file that covers the public API is the bare minimum for any decent open source project

Open Source Series: Starting a Project

or how to open your project to the world

Table of content

Recap

Be prepared for what’s coming

Code separation

Start with refactoring

Make it generic

Keep it simple

Eat your own dog food

Don’t get sued

Opening the project to the world

Going public

Creating a package

In any case

Sanity check

Further development

Wrapping it up

Are you really prepared to give a decent amount of your precious time to the community?

Owning an Open Source Project: Part 1

Intro or where the journey begins

Table of content

Who I am

So what is open source?

Open source is the concept of the information allowing the replication or modification of something being open to the public.

The open-source model is a decentralized software development model that encourages open collaboration.

A main principle of open-source software development is peer production, with products such as source code, blueprints, and documentation freely available to the public.

Despite its mailing list of interested editors, and the presence of a full-time editor-in-chief, Larry Sanger, a graduate philosophy student hired by Wales, the writing of content for Nupedia was extremely slow, with only 12 articles written during the first year.

Why bothering with open source

Together we’re strong

(Zarya, 2016)

Careful what you wish for

Wrapping it up

Make sure your intentions match your expectations

Angular 6: “ng test” with Jest in 3 minutes

Setting up Jest

Remove Karma related stuff:

Install @angular-builders/jest and jest:

Update your Typescript configurations:

In angular.json change @angular-devkit/build-angular:karma to @angular-builders/jest:run:

Running the tests with Jest

Further reading

Angular CLI 6 under the hood - builders demystified

Update:

Angular CLI builders

Angular CLI commands and architect targets

Architect targets configuration

Creating you own builder

Creating the package

builders.json

Builder definition

schema.json

Installing dependencies

The builder

Using the builder

Finishing words

Customizing Angular CLI 6 build - an alternative to ng eject

Angular CLI 1.x ng eject VS Angular CLI 6 builders

Extending underlying webpack configuration

And what about ng serve?

Additional sources

What is next

Install @angular-builders/jest and `jest`:

In angular.json change `@angular-devkit/build-angular:karma` to `@angular-builders/jest:run`: