Your custom React component

Let's take a look at the tools you should use during the course:

Cmder: The Cmder is a command line emulator running on Windows. I prefer cmder to the built-in windows command line tool because of the tabs. You can run and observe many processes at a time within one window with cmder.

PhpStorm: The Phpstorm is an Integrated Development Environment or IDE I use for my projects. It's built for php language but you can install many plugins support other languages like JavaScript. Phpstorm is not free so I won't use any special features. Therefore you can choose any other IDE or text editor to complete this course.

Git Bash: Git Bash is the default git command line tool. It will be the cmd for every single git actions during the course.

Let's summerize: git bash, an IDE or text editor, the proper nodejs and npm versions. That's all you need to complete this course.

The npm storage is the home of all npm packages. We want to build a package from our React component so we need an npmjs account. Open the npm website, click on the sign up link and go through the process. You can use your account to publish your component later. 

The very first step is check the version of our nodejs. Open your cmd and write node --version. If it's higher than v10, it's okay. The npm or node package manager comes with nodejs by default. Let's check the npm version as well. Write npm --version command, and hit enter. At least 6.0.0 is required.

If you don't have nodejs on your computer at all, just visit the official nodejs website and download the installer. If you have an older version of nodejs or npm follow the official update instructions on the nodejs website.

Open your empty project in your editor. One of the most important file we have to create is the package.json. It is required for all npm packages.Use JSON format to define the package data.

Start with the name field. You want to make a package under your npm username (so called scoped package), so start with an at sign following with your username. The package name ends with the project name "custom-button" after a slash.

The module value defines the production build file inside the custom-button project. If anyone will install our package via npm the module value will help the system to find our component as a library within the node_modules folder.

Add a short sentence as a description. You can write whatever you want, it doesn't matter.

All npm packages have their own version number in the npm storage. I usually use the semantic versioning starts with the version 1.0.0.

Fill the author part with your personal information.

The homepage and the repository are meta data used on your package npm page sidebar. If you don't leave them empty the package users can navigate to your component source code easily.

Add an MIT license. Talking about licenses is out of this courses scope but you can find the details on the internet easily.

The scripts block contains three commands. First is called build. We run build when a production build is needed. Webpack does the job for us.

The second is called docs. The docs command is responsible for build our demo site in and our component in development mode at the same time. We don't need a separated development build from our demo pages and our component, because Storybook can solve the two problems alone.

And last but not least the docs:build is for make a production build from our demo site. It's useful if you want to publish the demo site as a static html web page.

Finally, check your npm username in the package name value again. Open npmjs.com and compare your username on the npm website with the username in the package.json. If there are equals, you're good. 

Install the package dependencies. I'd like to draw your attention to the fact that we have development and product dependencies like a normal React project but I will install both of them as development dependencies. Just repeat the process after me, I promise I will explain the reason why later.

Npm install --save-dev webpack webpack-cli uglifyjs-webpack-plugin clean-webpack-plugin. These are for the build process itself.

Npm install --save-dev @storybook/react @storybook/components @storybook/addon-info storybook-addon-jsx. These modules are needed for make a demo site.

Npm install --save-dev react @babel/core @babel/preset-env @babel/preset-react babel-loader. So we installed the React library and the babel module to build the react component.

That's all we need for a demo site and a react component.

Readme.md is the home page of every GitHub projects. The .md extension means the markdown language. You can share informations on your project home page like how to install the component or what are the best practices.

Add readme.md file to your component root folder with a simple title. We can modify it later.

In order to build our component with Webpack you have to create a configuration file called webpack.config.js to the project root folder. The whole configuration goes into the module.exports block.

Set the build mode to 'production'.

Our components entry point is in the 'src/index.js' file.

Now we need to define the rules regarding to the output. The filename will be the name of our end product file.

The library value must be the same without the .js extension.

The library target is UMD which means Universal Module Definition. In connection with UMD you need to remember one thing: UMD is made for javascript modules which are capable of working everywhere, be it in the client, on the server or elsewhere.

The last part of the output is the target of our build.

Let's move on to the module section and define the building rules. We want to use Babel with the preset-env and preset-react presets to compile our component React code. Tell Webpack to use Babel for all javascript files except the files from the node_modules folder.

The optimization section needs only one Webpack plugin, the UglifyJS. UglifyJS is a javascript minifier and compressor. It can reduce our final file size.

Last but not least, add Clean Webpack plugin to the plugins part. The Clean plugin can remove everything from the 'dist' folder before a new build comes.

Import the webpack, path, clean and uglifyjs modules and we're done.

We need a .storybook folder to our project root. This folder contains everything related to our demo site. Create a config.js file to setup the demo system. Just one function call goes here like this. The first parameter is the folder where our demo cases will be settled and the second parameter is the module. Import the configure from storybook and we can move on. 

I want to activate the jsx Storybook plugin because we'd like to see the jsx source code of our component on the demo pages. It can help our users to understand how they can reproduce the given demo case.

Make a file called addons.js into the .storybook folder. Import the storybook-addon-jsx/register module. One more action is needed for activate the plugin. Load the plugin in the config.js with the setAddon function. Use JSXAddon module as a parameter of the setAddon call from the storybook-addon-jsx package. Import the plugin module itself. Import the setAddon function from storybook as well.

Lastly, create the stories folder under the storybook directory with the first demo page file index.js.

We have already set up our demo site so it's time to start our custom React component. We have already defined that our component source code is located in the src folder. Add an index.js file.

Import React and Component modules from react package. Create our component class called CustomButton. This class looks like a classic React component extends the built-in Component class. Just add a simple button to the render function to start with.

Create our very first demo case in the index.js file of the stories folder. We want to make a demo case for a React component so import React from the react package. Import the custom button component from our source folder.

You can add a demo page with the storiesOf function. Its first parameter is the name of the page. The demo site menu contains all pages name in a list. The second parameter is the module.

The addWithJSX function can generate a demo subpage for a demo case with the activated panels. We actived the JSX plugin if you remember. The subpage creator function needs one parameter for the name and annother one for the page content. Add just a simple instance of our custom button component because we don't have any additional features yet.

Open your Cmder and run npm run docs command. After the demo site build is finished the builder opens the site in your web browser automatically. As you can see we have the Custom button page with the simple sub-page. The simple sub-page shows the custom button component and its source code. From now our users can copy the jsx code from the bottom of the page to reproduce the example. More complex the demo case we have more valuable these jsx code snippets are. 

If you open the git bash and run git status command in the project you can see every new files and folders. The .idea directory is the meta folder of the PhpStorm IDE I use. I don't want to commit my personal IDE settings to the React component repository. The node_modules contains all project dependencies installed locally. We have to exclude the node_modules from the git repository as well.

You can ignore entities from the git repository with list them all in the .gitignore file. Create .gitignore file to your project root folder and add node_modules and .idea folders to it. If you use other IDE or text editor just add its own meta folder to the list. Give git status command again and now you don't see the ignored folders at all in the list. It means git doesn't care about these folders anymore.

Add our new files to the git stage with git add . command. Use git status command to check the stage state. Make our first commit with git commit command. Write your message and hit enter. After the commit is done run git status again to ensure no files left in the staging area. Now we can synchronize our local git repository with the GitHub server. Write git push and enter.

Open the GitHub website and navigate to the project. As you can see we uploaded our changes successfully. The project home page content is from the readme.md file as I mentioned earlier.

Build the demo site in production mode. We have the up and running development build process we don't want to stop so create a new tab in cmder. Rename the first tab to 'demo'. Right click on the tab, select 'Restart or duplicate' and click the 'Duplicate root'. Rename the new tab to 'demo-build'. Run npm run docs:build command to get the production build of the demo site as a static website. You can check the result if you open the index.html in your browser. 

Commit the production build of our demo site. Git status helps you to check the project stage. It's empty so add the entire docs folder with the git add . command. Check the stage again to ensure the next commit would contain the correct modifications. That's right, let's do the commit. Upload the new local commit to the GitHub server with git push. Refresh the project page to see the changes. 

Once the production build of the demo site uploaded we can activate the projects GitHub page. My goal is to show the demo as an online site without any external hosting. Click on the Settings icon and scroll down to the GitHub Pages section. Select 'master branch /docs folder' option under the Source and 'Save' it. If it's ok, GitHub gives an address where you can find your site from now. Open the link and yess, we are online.

The project menu has a new item called environment. The GitHub page activity log is shown on the environment page.

We don't want to copy all files and folder when a user installs our package via npm, just the component build file. You can exclude entities from your npm package using .npmignore file. Create .npmignore to the project root folder. Add everything except the dist folder which contains our component itself. 

The 'build' is one of the most important command we have because it makes the installable build of our component. Open Cmder and clone a new tab following the same process we learned before. Rename it to build.

Run npm run build command. As you can see the component product build file called custom-button.js is made and moved to the dist folder by webpack.

Firstly, you have to log in to npm. Run npm login command, and give your username and password pair from your npmjs.com account. Write your email address. Validate your active npm session with npm whoami command.

Open npmjs.com and go to your packages page. As for me I have already own 8 packages but It's quite likely that you have 0 at the moment.

Get back to the cmder. Npm publish command is built for upload your package to the npmjs repository. But before we do that, you need to give a version number to your package. Write Npm version 1.0.0. and hit enter. Ops, we got an error message says 'version not changed'. It's because we have already defined our starter version number at the beginning in the package.json file. The npm version command try to update this value to the 1.0.0. but it's not differ from our initial value so that we have the error message. It's not a problem, our package.json have the version 1.0.0 so we can move on. Remember, every time you want to upload a new release, just use npm version command to set the proper version number.

Run npm publish to upload the component. We have an error again says 'You must sign up for private packages'. The reason of this error is that the scoped packages are with private access by default. In order to upload a private package you have to upgrade your free npm account to a paid one. We don't want to make our package private but still keep the scope if it's possible at all.

In spite of the error message doesn't tell anything about this option, yes, it's possible. But before I teach how, I have to fix something. If you take a look at the file list npm tried to publish you can see the docs folder too. As I mentioned earlier we'd like to publish only the custom-button.js file as our end product, nothing else. Open your .npmignore and add docs folder to the list.

Run npm publish again to ensure the docs folder is not in the list anymore. It looks so much better, but we still have the error.

The trick is using --access=public parameter with the npm publish command. It allows you to upload a public scoped package under your free npm account. No more error messages and your custom react component is released.

Refresh the npmjs website, and now you can see your brand new package. Click on the custom-button package to go its home page. All information is on this page like version, install command, collaborators and so on.

You need to extend your webpack configuration to work with the sass css language. A new rule is needed for all .scss files. Add the following three loader to the rule: style-loader, css-loader, sass-loader. Webpack knows how to build sass files from now.

I usually put my scss files to the style folder in the project root. Add a button.scss file.

Our component contains only one button element so we should write a basic sass block for buttons. Change the border to red, add some padding and a gray background color.

The last step is the import of the button.scss file in the component.

Switch to the cmder demo tab to see the demo site development build status. It gives an error we will fix in the next lecture easily.

The error message says we need a loader to work with sass files in the webpack configuration and the storybook configuration as well. We did that only in the webpack config, so fix the storybook configuration now.

Add webpack.config.js to the .storybook folder. One rule is needed regading to the scss files under the module section. Set the rule for all scss files and add style-loader, css-loader and sass-loader as loaders.

Stop demo site development build by hit ctrl + c and yes then run npm run docs command. We need to restart the build process because the storybook configuration changed. Annother error arises: 'can't resolve sass-loader'. Let's check our package.json dependencies part to ensure we don't have the loaders. Really, that's true. It means we have to install the three loaders. Stop the process with ctrl + c and yes.

Run npm i (which means install) css-loader style-loader sass-loader. Try to build the demo site in development mode once again. I missed the node-sass module but it's needed. Stop the process and install node-sass.

Run npm run docs. This time the site can be built without any errors, cool.

Let's see how easy using sass to create your component design once you set the configuration. If I change anything in the button.scss file I can see the result immediately.

In the previous lecture we finished the sass support configuration. Check the git stage and make a commit to save our result. Upload the commit with git push. Switch to the browser and refresh GitHub page to see whether the commit arrived or not. That's ok so we can continue. 

We have already published the version 1.0.0 from our component before. This time we need to upload the next version because the component have a new design thanks to the sass support.

Set the version 1.1.0 with npm version command. If you check the package.json file you can see the version number is increased automatically. The next step is to make a new production build from the component. Run npm run build. Now we can publish the package.

Check the package website. The last version is the 1.1.0. so the second release is published successfully. You can see all versions under the versions tab.

Badges are useful to inform users in an intuitive way. I usually use shields.io website to get my badges. Go to the versions section. Scroll down to find the npm (scoped) option. Click on the link. Fill the scope field with your npm username and the package name with the custom-button. Push 'Copy Badge URL' button.

We'd like to show our badges in the home page of our git repository. Open readme.md file and add the version badge as an image inside a link. Use the markdown language.

Finally, we have the version badge displays the latest version of our npm package. If anyone clicks the badge the npmjs website will be opened.

Make a git commit to save our latest modifications. Add all changes to the git state and commit. The git push is the last movement.

Reload the GitHub page to see the working badge on the home page. You can take your component to the next level using badges. It looks like more professional.

Let's consider what if someone want to use our custom button package in a project. Clone our last Cmder tab and rename to 'random-project'. Change our location outside the components folder. I go back to my Development folder and create a new directory called 'random-project'.

Create a new React project with the build-in 'create react-app' command. After the setup is done you get an up and running React project. This is how the random-project folder looks like. Go to the random-project sub-directory. Run npm start to build the random-project. If you see the spinning react icon your random project is running.

Open the package.json. The random-project only has three dependencies at the moment. Stop the random project build process to install our component using the installer command from the npmjs website. Start the random project again. The custom button becomes a dependency of the random project.

Open the App.js file and add a custom button under the big spinning react image. Import custom button from our package. Create a new instance from the button and save the file. Switch to the browser and our custom button is on the page.

We have to update the product build of our demo site to follow the development build changes. If you open the docs folder index.html file the older version of the demo site will be shown. Run the npm run docs:build command to rebuild the production version. Make a new git commit after the build is ready. Push the changes and open the GitHub page to check the upgrade. Click on the environment tab to see the last action. Now we have the latest version online. 

You can create a custom badge with Shields.io easily. Scroll down to the 'Your Badge' title. I want to show a badge pointing to my online demo site, so I write the subject 'demo' and the status 'site'. I choose the green color. Push 'Make Badge' button. Copy the url and take it to the readme.md file next to the npm version badge. Copy the demo site address and create a wrapper link around the image. It's done.

Just a quick git commit and push like in the previous lectures. Refresh GitHub page and there is the second badge. Click the demo badge to open the demo site.