Forem: Dawid Wojda

Create CLI for your React project in 5 minutes with Pli

Dawid Wojda — Thu, 06 Apr 2023 13:44:07 +0000

If you have ever worked with Nest.js (which is a backend framework for Node.js) you may know that they have a nice terminal CLI which allows creating common application components like models, controllers or decorators. I really enjoyed working with it and missed the experience later in many projects. I think especially in frontend projects with React. I love React but one of it’s downsides (and biggest advantages at the same time) is that React is a library and by itself it does not provide any tooling which for bigger projects would be very useful.

So, how can we create the nice experience of having CLI for our project while staying away from React principle of being a library? Pli can answer this question. Pli is a small library which will turn your files into nice terminal CLI for project in just minutes.

How to start with Pli?

Pli is an NPM package, so you can easily install it by typing npm install -g @dawiidio/pli or yarn global add @dawiidio/pli in your terminal. Later create directory where you want to experiment with Pli, or choose one existing one and checkout there.

When we have Pli installed and we are in our directory run pli init . It will create a templates directory in current location with example template inside. The example template is hello.ts the below code inside it:

export function hello(): string {
    return 'Hello $NAME$';
}

As you can see it’s just a normal TypeScript function. One unusual thing about it, is $NAME$ inside of string. This is a Pli variable. Pli will extract this variable from our example file and later it will prompt for it’s value in cli to replace $NAME$ with provided value at the end. Want try it? Run

pli
# it will ask you which template you want to use
# ? Select template (Use arrow keys)
# ❯ hello.ts

For now we have just one template - hello.js so let’s go with it.

# next question is about the directory where you want to save the output file
# you can leave it empty, so the output will be saved in current directory
? Output directory

# and the las question is about our variable $NAME$!
? Insert value for NAME :

After providing values for variables Pli will replace all variables in template file and save the output in directory provided in the second question. Final message from pli is paths tree of generated result files and directories, like the below:

Following structure was created inside directory /path/to/directory
├─ hello.ts

I entered the value “Dawid” for variable $NAME$ so If I will open hello.ts it will contain the following text:

export function hello(): string {
    return 'Hello Dawid';
}

That’s it! Our most basic Pli template is ready to use 🔥

More complex example

As you saw in previous example, creating templates with Pli is fast and simple since they are just files and variables inside them. Nevertheless simplicity of Pli does not imply that it can’t deal with more complex tasks. Now I want to show you how to create template for React component with css modules styles.

In my application I keep components in directory src/components , each component has it’s own directory inside and in this directory I have component and it’s CSS file. What I want to do, is to create Pli template which will generate this component for me.

First, let’s create following structure in templates directory:

# ├─ $COMPONENT_NAME$/
# │  ├─ $COMPONENT_NAME$.module.css
# │  ├─ $COMPONENT_NAME$.tsx

mkdir templates/$COMPONENT_NAME$
touch templates/$COMPONENT_NAME$/$COMPONENT_NAME$.module.css
touch templates/$COMPONENT_NAME$/$COMPONENT_NAME$.tsx

Now, we can fill the files with content, in my case it looks like this:

/* templates/$COMPONENT_NAME$/$COMPONENT_NAME$.module.css */

.$NAME$Root {

}

// templates/$COMPONENT_NAME$/$COMPONENT_NAME$.tsx

import React, { FunctionComponent } from "react";
import styles from './$NAME$.module.css';

interface $NAME$Props {

}

export const $NAME$:FunctionComponent<$NAME$Props> = ({  }) => {

    return (
        <div className={styles.$NAME$Root}>
            Component $NAME$
        </>
    )
};

You can now run this template and it will create nice react component with it’s styles. One more thing we can improve is to add default output directory, so we won’t have to type src/components each time. To do it we need to add pli config file, you can do it easily by running pli init -c . File pli.config.ts will appear in current directory, to improve our template we will add to it following content:

import { Template, IConfig } from '@dawiidio/pli';

const config: IConfig = {
    templates: [
        new Template({
            // readable name, instead of "$COMPONENT_NAME$" you will see "React Component" in cli
            name: 'React Component',
            // if you want to extend from existing template in templates directory you need to provide its name
            id: '$COMPONENT_NAME$',
            // all will be generated relative to src/components directory
            defaultOutputDirectoryPath: 'src/components',
        })
    ]
}

export default config;

And that’s it! Our template for React component with css modules file in src/componentsis ready to run. After running it you should see the message like the below one, but with your component name (in my case is was TestFilter)

Following structure was created inside directory /myProject/src/components
├─ TestFilters/
│  ├─ TestFilters.module.css
│  ├─ TestFilters.tsx

Of course you may want to add some validation for variables, introduce new ones, create dynamic templates etc. If you want to learn more see the examples in repo https://github.com/dawiidio/pli/tree/main/examples

Summary

Pli is a very simple but powerful tool, I hope it will help you maintaining your projects on daily basis. Also, as you may already noticed, Pli is language agnostic, so if you want to you can use it with any other language than just TS or JS. If you liked it or want to know more please visit the repo https://github.com/dawiidio/pli since Pli does not have the webpage as it’s own yet. Have a nice day ❤️

How to name a boolean variable correctly?

Dawid Wojda — Wed, 13 Oct 2021 19:49:28 +0000

What is it about?

Article treats about naming convention for boolean variables and functions (selectors) in context of React+Redux stack because I found people are confused about it.

TL;DR

You should use verbs like is or should in selectors. Consider selectors as questions and variables/constants as the place where you keep the answers to them. Nouns like car, admin or more complex sentences like affirmative statement eg. displayAdsSection holds answers to questions. Below example:

// define question
const shouldDisplayAdsSection = (state: State): boolean => {
    return state.permissions.displayAdsSection &&
           state.user.plan === 'free';
};

// ask question, receive answer then save it
const displayAdsSection = useSelector(shouldDisplayAdsSection);

// do whatever you want with answer
if (displayAdsSection) {
    return <AdsSection />;
}

Explanation

Let's do a little experiment on the beginning to better understand the problem. Assume that you found in project code something like this:

...

const isItBoolean = ...;

...

What is your guess? What do you think hides under const isItBoolean ? Is it actual boolean or is it a method that performs the check? I can't hear you now (but be my guest and leave your answer in comments!). I can tell my guess - selector. It is a selector. Why?

Text were inspired by argument which I had with colleagues from work. One of them wrote comment on my pull request like:

Instead of displaySection it should be shouldDisplaySection . This is a boolean

And that obvious last part "This is a boolean" was a trigger. Why on earth should I add a verb to variable name to indicate boolean type? I didn't get straight answer why but I had some guess'.

We think variable named like shouldDisplayAdsSection holds answer to the question should I display ads section?.
And concept is good, but the execution is bad. Indeed variable holds answer, but unfortunately it has a question in the name. So, when you look at it, it produces more questions - should I display section? Should I? Maybe not. Are you asking me? Why you making me decide?
Reading the code should remove questions, not creating them. We spend a lot of time on reading code not writing it, this is the reason why we should care about proper and easy to read names.

Solution to above is very simple if we adopt the principle of naming variables with affirmative statements. According to principle, variable which holds the answer may look like displayAdsSection.

Better? IMO yes. We eliminate the question. We have a valid affirmative statement. But... if we have the answer where is the question now?

Selector is our question. In general methods and functions are our questions. They contain some instructions that define questions. For selector we can recycle eliminated earlier name: shouldDisplayAdsSection.

And here is the code with applied above rules:

// define question
const shouldDisplayAdsSection = (state: State): boolean => {
    return state.permissions.displayAdsSection &&
           state.user.plan === 'free';
};

// ask question, receive answer then save it
const displayAdsSection = useSelector(shouldDisplayAdsSection);

// do whatever you want with answer
if (displayAdsSection) {
    return <AdsSection />;
}

Problems

In real life of course you will face some more sophisticated problems, for example like this

class Car {
    //...
}

interface State {
    car: Car
}

const isCar = (car: any):car is Car => car typeof Car;
const selectCar (state: State): Car => state.car;

// here we have some problems...
const car = selectCar(state);
const car = isCar(car);

which one should be named car? Remember, this is a naming problem, try to play with more specific names for selectors or think about synonyms, maybe something fits better. I see it like this:

const isTypeofCar = (car: any):car is Car => car typeof Car;
const selectCar (state: State): Car => state.car;

const car = selectCar(state);
const typeofCar = isCar(car);

if (typeofCar) {
   render(car);
}

Summary

The only standard you need for booleans is an affirmative statement that evaluates to either true or false, this rule works across languages and frameworks. Thanks to above rules your code will look more like sentences written in natural language, which will translate into better readability for your colleagues and future you.