Forem: amalv

A cleaner Github workflow: one commit per Pull Pequest

amalv — Fri, 01 May 2020 20:09:17 +0000

In this guide you'll learn how to keep a cleaner Git history having one commit per Pull Request (hereinafter referred to as "PR").

Benefits of a linear Git history

Easier to do a Git bisect in order to find bugs: find the PR that has the bug more effortlessly because there is a one to one relationship between PRs and commits.
Git log history will be more readable: since it will be a shorter and concise Git history.
Commit early and commit often: quick disposable messages in case you want to go back and not start from the beginning when working on a feature or bug fix.

Configure your Github repository to allow rebase merging

The Github merge button for the PRs adds merge commits by default. As a first step update your Github repository settings in order to change this behaviour.

Commit early and commit often

If you fail to commit and then do something poorly thought out, you can run into trouble. Additionally, having periodic checkpoints means that you can understand how you broke something.

Let's say you are trying to add theming support to your app, here is an example of several commits in your feature branch:



git log --pretty=oneline



2ae83a39277d4940ce6d3c76c742047130be4adb (HEAD -> add-theming) Finish
0b47fcbaa276323fc43134652f77ccd49d072e1b WIP
4c2e809097df993ffc57b4c8ce01de1c0042efb2 Fix theming provider
db368b434628d3859c5f36cf7c74d9788af34bdf Add theming support
356351b29c79682393ee10ee6c6a6c97fc678d7b (origin/master, origin/HEAD, master) Initial commit

When finished, do a git rebase



git rebase -i master

This will prompt your editor to allow an interactive rebase:



pick db368b4 Add theming support
squash 4c2e809 Fix theming provider
squash 0b47fcb WIP
squash 2ae83a3 Finish

Squash all commits except the first one.

Save the changes and another screen will appear with your commit messages:



# This is a combination of 4 commits.
# This is the 1st commit message:

Add theming support

# This is the commit message #2:

Fix theming provider

# This is the commit message #3:

WIP

# This is the commit message #4:

Finish

That you can rewrite it with something similar to this:



# This is a combination of 4 commits.
# This is the 1st commit message:

Add theming support

- First step
- Second step
- Third step

# This is the commit message #2:

# Fix theming provider

# This is the commit message #3:

# WIP

# This is the commit message #4:

# Finish

Here the unuseful messages are commented out, and if we have useful ones or want to add more info, we can do it using bullet points below the commit title (in this case Add theming support)

Once finished, push the changes to your Github repository:



git push --set-upstream origin add-theming

Create the PR and merge changes

Now go to the Github repository, you'll se a button to create the PR:

Once it's created, you'll see your changes, the title will be the first line of your commit message, and the body will be the rest of the commit message:

Click the "Create Pull Request" button and the PR will be created:

Finally press the "Rebase and merge" button.

Conclusion

That's it!

If you follow this workflow you'll always have a single commit for each PR with the benefits mentioned before.

If you want to comment on your preferred workflows and the reasons why you like them or you have suggestions or criticisms for this workflow, let me know in the comments.

How to setup Semantic Release for a React app or a Next.js app

amalv — Tue, 28 Apr 2020 21:35:25 +0000

Overview

In this guide you'll learn how to setup Semantic Release for a React app or a Next.js app.

This will allow you to follow a workflow that performs fully automated releases for Github and enforces the Semantic Versioning specification based on your commit messages.

Here is an example from the official documentation of the release type that will be done based on commit messages:

Commit message	Release type
`fix(pencil): stop graphite breaking when too much pressure applied`	Patch Release
`feat(pencil): add 'graphiteWidth' option`	~~Minor~~ Feature Release
`perf(pencil): remove graphiteWidth option` `BREAKING CHANGE: The graphiteWidth option has been removed.` `The default graphite width of 10mm is always used for performance reasons.`	~~Major~~ Breaking Release

Tools such as commitizen or commitlint can be used to enforce valid commit messages.

You can use the commitizen extension to add commitizen support to Visual Studio Code.

Basic setup

First, create a Next.js app using Create Next App:



npx create-next-app semantic-release --example with-typescript --use-npm

Or if you prefer to use only React, use Create React App and run:



npx create-react-app semantic-release --template typescript --use-npm

Create a Github repository

https://github.com/new

In this example I called it: semantic-release

Link local repository to Github repository



git remote add origin git@github.com:<username>/<repository-name>.git
git push -u origin master

Github token

A Github token must be created in order for Semantic Release to be able to publish a new release to the Github repository.

You can read here how to create a token for Github. You need to give the token repo scope permissions.

Once you have the token, you have to save it in your repository secrets config:



https://github.com/<username>/<repositoryname>/settings/secrets

Use GH_TOKEN as the secret name.

Install Semantic Release Git and Changelog plugins



npm install --save-dev @semantic-release/git @semantic-release/changelog

These plugins are necessary in order to create a Changelog and publish the new release in Github.

Add Semantic Release config to package.json

Add the following config to your package.json:



  "private": true,
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/github",
    "@semantic-release/npm",
    "@semantic-release/git"
  ],
  "release": {
    "prepare": [
      "@semantic-release/changelog",
      "@semantic-release/npm",
      {
        "path": "@semantic-release/git",
        "assets": [
          "package.json",
          "package-lock.json",
          "CHANGELOG.md"
        ],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  }

When you set the private property to true, it skips the publication to the NPM repository, which in this case we don't want to do.

Setup Github Actions

Github Actions will be used to create new releases of your app.

You must store workflows in the .github/workflows directory in the root of your repository. Once you created the directories, add a main.yml file inside with the following config:



name: Semantic release 

on:

  push:

    branches:

      - master

jobs:

  publish:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2

      - name: Setup Node.js

        uses: actions/setup-node@v1

        with:

          node-version: 12

      - name: Install dependencies

        run: npm install 

      - name: Build app

        run: npm run build 

      - name: Semantic release

        env:

          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}

        run: npx semantic-release

Commit and push changes

Use the following commands:



git add .

git commit -m "feat: Add Semantic Release and Github Actions"

git push

Conclusion

Congratulations!

If you followed these steps, you should now have triggered Github Actions:

Also, if you check the release tab in your repository, you'll also see your first published release:

And finally, a Changelog file should have been automatically generated and published:

You can find the complete code for this guide in this github repository

Publish Storybook components to NPM using Semantic Release and Github Actions

amalv — Thu, 12 Mar 2020 16:54:51 +0000

Overview

In this guide you'll learn how to publish your Storybook components to NPM. In this way the components can be easily distributed and then consumed by the client apps.

Semantic Release will be used in combination with Github Actions in order to automate the release versioning.

Basic React Setup

First Create React App must be installed. The following command will generate a Create React App with Typescript support and NPM as the package manager:

npx create-react-app storybook-npm --template typescript --use-npm

Note that instead of storybook-npm you'll have to choose your own unique name to publish to NPM or use the scoped package approach.

Initialize Storybook

Add Storybook to the project:

cd storybook-npm
npx -p @storybook/cli sb init --story-format=csf-ts

You can check that it works by running the npm run storybook command.

Install and configure Semantic Release

npm install --save-dev semantic-release

Semantic Release has a perfectly fine out of the box default config, the only thing we need to do here is to add the plugins we want to use in the package.json:

  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/github",
    "@semantic-release/npm",
    "@semantic-release/git"
  ],

Clean up files

Since this project is not going to be used as a client, let's clean up a little bit and remove all the unnecessary files:

cd src
rm -rf stories/*
git rm -rf .

Install styled components

Styled Components is going to be used to style our components:

npm install styled-components @types/styled-components

Add button component

As an exportable component example we are going to create a button.

In the src folder create a new components folder.

Inside the components folder add the Button component:

Button.tsx:

import styled from "styled-components";

export interface ButtonProps {
  primary?: boolean
}

export const Button = styled.button<ButtonProps>`
  /* Adapt the colors based on primary prop */
  background: ${props => props.primary ? "palevioletred" : "white"};
  color: ${props => props.primary ? "white" : "palevioletred"};

  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid palevioletred;
  border-radius: 3px;
`;

Still inside the components folder add an index to export this and future components:

index.ts

export * from "./Button";

Add index to `src` folder

index.ts

export * from "./components";

This will export our components in order to allow clients to consume them.

Add the Button stories inside the `stories` folder

import React from 'react';
import { action } from '@storybook/addon-actions';
import { Button } from "../components/Button";

export default {
  title: 'Button',
  component: Button,
};

export const Default = () => <Button onClick={action('clicked')}>Default Button</Button>;
export const Primary = () => <Button primary onClick={action('clicked')}>Primary Button</Button>;

Check that the new component is being displayed in Storybook

npm run storybook

You should now see the Default and Primary buttons being displayed in Storybook under the Button story.

Create a Github repository

https://github.com/new

In this example I called it the same name as the package: storybook-npm

Link local repository to Github repository

git remote add origin git@github.com:<username>/<repository-name>.git
git push -u origin master

Commit and push changes

git add .
git commit -m "feat: Add button component"
git push

Github and NPM tokens

We need to get Github and NPM tokens. This is needed in order for Semantic Release to be able to publish a new release for the Github repository and for the NPM registry.

You can read here how to create a token for Github. You need to give the token repo scope permissions.

And here you can read how to create a token in NPM. You need to give the token Read and Publish access level.

Once you have the two tokens, you have to set them in your repository secrets config:

https://github.com/<username>/<repositoryname>/settings/secrets

Use GH_TOKEN and NPM_TOKEN as the secret names.

Setup Github Actions

Inside the root of the project, create a .github folder, and inside the .github folder, add a main.yml file with the following content:

name: Semantic release 

on: push
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12
      - name: Install dependencies
        run: npm install 
      - name: Build app
        run: npm run build 
      - name: Semantic release
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Commit and push changes

git add .
git commit -m 'feat: Add github actions'
git push

Because of the config previously added, the push will trigger Github Actions which runs Semantic Release. You can see the results in your repository action tab.

Github Release

If everything went well, you should see in the action results that every step was succesfully executed.

And in the code tab you can see now that a new release has been created.

However, the NPM package has not been published, in order to fix this, a couple of changes need to be made.

NPM Release

Update the tsconfig.json file:

{
  "compilerOptions": {
    "outDir": "dist",
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "commonjs",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false,
    "jsx": "react"
  },
  "include": [
    "src"
  ]
}

You'll also need to remove the private property from package.json in order to be able to publish to NPM and add the files and main entries:

  "files": [
    "dist"
  ],
  "main": "dist/index.js",

file will indicate to NPM that dist is the folder to be included when the package is installed as a dependency.

main represents the dependency entry point.

Commit and push changes:

git add .
git commit -m "Enable NPM registry support"
git push

This should trigger again Github Actions and this time the package will be published to the NPM registry.

Use the dependency with a client app

To try the NPM package, we'll create a new Create React App:

npx create-react-app storybook-consumer --use-npm

Then install the dependency:

npm install storybook-npm

Edit App.js in order to test it:

import { Button } from 'storybook-npm';
...
<Button>Test</Button>

And start the app:

npm start

You should now see the button in the main page.

Conclusion

Having a good strategy for releasing your Storybook components can make things easier to maintain. Semantic Release in combination with Github Actions automates the release process so you only have to worry about choosing the appropiate commit messages.

Tools such as commitizen or commitlint can be used to enforce valid commit messages.

You can find the complete code for this guide in the github repository

Set up Storybook using Typescript, Material UI and Styled Components

amalv — Mon, 09 Mar 2020 20:33:40 +0000

Overview

In this tutorial you'll learn how to create a basic foundation for Storybook using Typescript, Material UI and Styled Components.

MDX will be used as the syntax for Storybook stories.

Basic React Setup

First Create React App must be installed. The following command will generate a Create React App with Typescript support:

npx create-react-app storybook --template typescript

Initialize Storybook

Add Storybook to the project:

cd storybook
npx -p @storybook/cli sb init --story-format=csf-ts

Add and configure Storybook docs

Storybook docs will add support for the Docs tab and the MDX format.

npm install -D @storybook/addon-docs

Inside the .storybook folder you have to update the main.js file in order to support Storybook docs:

module.exports = {
  stories: ["../src/stories/**/*.stories.(ts|tsx|js|jsx|mdx)"],
  addons: [
    '@storybook/preset-create-react-app',
    '@storybook/addon-actions',
    '@storybook/addon-links',
    {
      name: "@storybook/addon-docs",
      options: {
        configureJSX: true
      }
    }
  ],
};

Add Material UI and Styled Components

npm install @material-ui/core styled-components

Check if Storybook runs correctly:

npm install
npm run storybook

You should be able to see the default stories.

Add a Button component

As an example, create a components folder inside src and add a Button.tsx file inside:

import styled from 'styled-components';
import Button from '@material-ui/core/Button';

const StyledButton = styled(Button)`
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border-radius: 3px;
`;

export default StyledButton;

Here the Button component from Material UI is being styled using Styled Components.

Add Button story

Create a Button.stories.mdx file inside the stories folder:

import { action } from '@storybook/addon-actions';
import { Meta, Story, Preview, Props } from "@storybook/addon-docs/blocks";
import Button from "../components/Button";

<Meta title="Material Button" />

Here's some _markdown_!

# Preview

<Preview>
  <Story name="Default">
    <Button variant="contained" onClick={action("Default button clicked")}>Default</Button>
  </Story>
  <Story name="Primary">
    <Button variant="contained" color="primary" onClick={action("Primary button clicked")}>Primary</Button>
  </Story>
  <Story name="Secondary">
    <Button variant="contained" color="secondary" onClick={action("Secondary button clicked")}>Secondary</Button>
  </Story>
</Preview>

# Props

<Props of={Button} />

Fix CSS injection order using a decorator.

Styled Components styles will be overrided by Material UI, in order to fix this a decorator must be added.

Create a config.js file inside .storybook folder:

import React from "react";
import { StylesProvider } from "@material-ui/styles";
import { addDecorator, configure } from '@storybook/react';

const StylesDecorator = storyFn => (
  <StylesProvider injectFirst>
    {storyFn()}
  </StylesProvider>
);

addDecorator(StylesDecorator);

Conclusion

Congrats! If you followed these steps you should now have a good foundation to start creating your own stories with a solid Storybook initial configuration.

You can find the complete code in this github repository

Forem: amalv

A cleaner Github workflow: one commit per Pull Pequest

Benefits of a linear Git history

Configure your Github repository to allow rebase merging

Commit early and commit often

When finished, do a git rebase

Create the PR and merge changes

Conclusion

How to setup Semantic Release for a React app or a Next.js app

Overview

Basic setup

Create a Github repository

Link local repository to Github repository

Github token

Install Semantic Release Git and Changelog plugins

Add Semantic Release config to package.json

Setup Github Actions

Commit and push changes

Conclusion

Publish Storybook components to NPM using Semantic Release and Github Actions

Overview

Basic React Setup

Initialize Storybook

Install and configure Semantic Release

Clean up files

Install styled components

Add button component

Add index to src folder

Add the Button stories inside the stories folder

Check that the new component is being displayed in Storybook

Create a Github repository

Link local repository to Github repository

Commit and push changes

Github and NPM tokens

Setup Github Actions

Commit and push changes

Github Release

NPM Release

Use the dependency with a client app

Conclusion

Set up Storybook using Typescript, Material UI and Styled Components

Overview

Basic React Setup

Initialize Storybook

Add and configure Storybook docs

Add Material UI and Styled Components

Check if Storybook runs correctly:

Add a Button component

Add Button story

Fix CSS injection order using a decorator.

Conclusion

Add index to `src` folder

Add the Button stories inside the `stories` folder