DEV Community: naveennamani

Hacktoberfest: let's contribute to my project offline-docs

naveennamani — Sat, 01 Oct 2022 07:07:50 +0000

What is it?

Offline-docs is a repository with a collection of scripts to generate offline documentation for many open-source projects. It's been a while I introduced this project in my earlier post. Since then, I kept adding more and more projects to the repo and now it contains more than 50 scripts.

This hacktoberfest let us make this project even more useful by contributing your valuable time and efforts. This post describes many ways in which you can make code and non-code contributions. But first, let me explain quickly how the project is organized.

Show me the code

naveennamani / offline-docs

A collection of scripts to build offline documentation for your favourite frameworks/libraries. Simply search, copy/paste the commands and enjoy.

Offline-docs

A collection of scripts to build offline documentation for your favourite frameworks/libraries/projects. Simply search, copy/paste the commands and enjoy.

Available projects

Currently 51 projects available

Backend
- expressjs
- nodejs
Blockchain
- ethereum
- hardhat
- matic.js
  - Direct links
- polygon (matic)
- solidity
  - Direct links
- waffle
  - Direct links
Build tools
- vite
Cross platform app development
- React Native
- tauri
CSS frameworks/libraries
Frontend javascript frameworks/libraries
- axios
- react-redux
- reactjs
- redux
- redux toolkit
- RxJS
- vuejs V3
Javascript testing libraries
Machine learning
Programming languages
- gobyexample
Python
- pydantic
- requests
  - Direct links
- sqlalchemy
  - Direct links
- typer
Python web frameworks
- bottle
  - Direct links
- django
  - Direct links
- fastapi
- flask
SSG, SSR
Other

But why? / Motivation

Learning or working on a new…

View on GitHub

Setup

This project uses yaml files for storing data related to each project. The projects are grouped into project groups based on the common theme. This project uses node.js to handle these yaml files and to automatically and consistently generate README.md file.

So, before contributing anything, first install all dependencies by running npm run install.

Contributing to the project

Adding a new project

For adding a new project or project group a script cli.js is provided. When you run the script, it asks for the required information and stores them in yaml files and updates the README. The git clone ... & cd dir commands will be added by the script. So, only enter the required commands to be run after cloning the repository.

When in doubt, run the script and look at the generated readme file.

Modifying/updating an existing project

For modifying details of any existing project, modify appropriate yaml file in projects folder and then run index.js script to format the yaml files and to update the README.md file with the changes.

Non-code contributions

Testing the scripts

As the source code of the project changes, sometimes we may need to update the scripts. That is why last tested details are given for each project. If you happen to be testing the script and it worked, you can update the last tested date.

To limit the possibility of simply updating the date without actually testing, you are required to post a screenshot in the PR request comments showing that you are able to access it offline.

Request more projects

If you require scripts for any project that you want to generate offline documentation for, you can add them in the TODO.md file with following details

Website URL
Source code repo for the project
Any commands that you've already tried (optional)

The source code repo URL is required and it shows that you've done your own research.

Other contributions

You can follow the issues and can work on them if interested. But please let me know before you start working on it, so another person may not waste their time.

Looking forward for your contributions :)

How to stay motivated on your side projects? 🤔🤷‍♂️

naveennamani — Sun, 24 Apr 2022 06:14:27 +0000

We all have so many half-baked projects that we don't want to go back to. Still, we have unicorn ideas that we can't wait to start. In turning that unicorns to donkeys we all become developers.

But how do you stay motivated in creating those donkeys? Well here are some of my opinions and learnings.

Whether half-baked or full, learn the skills of baking

Side projects are for learning at your own pace.

Most of my programming experience comes from my side projects. I learnt multiprocessing and process queues in python when I thought about gifting my friend a mosaic image. Even though it was a bummer, later it helped me at my workplace. Similarly, I touched on so many things (unfinished) just to learn something new.

What makes learning at workplace different from side projects is working at your own pace. And personally I feel more confident about my knowledge when I learn it in my own way. Most of you might agree on this one, so if you like learning at your own pace, start a new side project around what you want to learn.

Do something today that your future self will thank you for

No matter how small your side project is, sometimes it helps you or someone else at the right time. Whether it's 10 lines automation script, or 1000 lines of code, when time comes, you appreciate yourself. This may not always happen, but keeping your projects code accessible will help you in solving the problems that you already solved once.

So while starting a new project, just make sure you keep the code accessible. May be push it to a private repository, or make a new secret gist.

Keep the ideas coming

Ideas are so powerful, they start small and when given enough thoughts and time, they can solve real world problems.

All side projects starts with some idea. Whether it's useful or not, unique or copied, dumb or smart, but there will always be some idea that you try to implement. Many times one idea lead to another, whether its small improvements or your unique signature, it helps you in exploring many things. With time and exploration, you'll understand if an idea is worth spending your time. Every idea you understand, will help you with some new ideas and solutions. Remember, at the end of the day, it's your ideas that solves the problem and not the number of languages/libraries/frameworks you know.

So, keep pushing your brain to process more ideas, and to generate more ideas.

These are just my opinions on what I learned through many of my side projects. Comment down below your experience and learnings :).

Happy coding!

Introducing offline-docs, collection of scripts to generate offline documentation of open-source projects

naveennamani — Sun, 17 Apr 2022 01:35:49 +0000

Offline-docs is a repo with collection of scripts to build offline documentation for your favourite frameworks/libraries. Simply search 🔎 for your tool, copy/paste the build commands and enjoy.

But why? / Motivation

Learning or working on a new language often requires referring to the official docs multiple times. With the rise of Static Site Generation (SSG) many documentation sites are now open-source and can be built for offline usage. This project aims to collect all such websites and the build commands to have a knowledge of widely used SSG tools.

How to use this repo

Details about each tool such as website, source code repo and build commands are given in README page of the repo. Once you are on the repo

Find the framework/library/tool for which you want to build the documentation (you can search in the Available Tools or with Ctrl+F)
Open a new terminal
Copy paste the build commands shown for the tool
Open the output dir as mentioned in the last command (or) unarchive the .tar.gz file in your preferred location and rename the folder
Use any static site serving tools like serve (npm package) or simply python -m http.server. (We recommend using serve package)

Currently available tools

Blockchain
- ethereum
- hardhat
Build tools
- vite
CSS frameworks/libraries
- daisyui
- material ui
- tailwindcss
Frontend javascript frameworks/libraries
- reactjs
- vuejs v3
Javascript testing libraries
- chaijs
- mochajs
Other
- eslint

Many more websites are coming soon (including Mozilla Developer Network (mdn) 😉). So, go to the repository, create a star ⭐ and show your love ❤️ towards the project.

Thanks for your time!

Visit my blog for latest articles related to web development
https://naveennamani.github.io/blog and
for projects like this.

Using vite-plugin-ssr with mdx-js, solving ESM only library problems, understanding vite configuration and writing vite plugins

naveennamani — Thu, 31 Mar 2022 19:01:28 +0000

vite-plugin-ssr is vite plugin which allows us to build websites with Server Side Rendering, Client Side Rendering, Single Page Applications and Static Site Generation all in one. This plugin is like Next.js but provides more control over each page and for any of your favorite frontend framework. Please visit the website to learn how to use this plugin.

In this tutorial we'll learn how to setup mdx-js library for vite project for building markdown based websites and to prerender them using vite-plugin-ssr to generate static websites.

The vite-plugin-ssr github repo contains example projects which you can clone and start with. For example react-full example already provides a setup for working with mdx-js library. The intention of this tutorial is to show how to solve some of the problems I encountered while using the mdx-js library and vite-plugin-ssr prerender feature.

Project setup

First of all, we need to setup a vite + vite-plugin-ssr based project. To scaffold a vite-plugin-ssr project simply execute

npm init vite-plugin-ssr

Give your project a name (I named it nn-blog) and select the frontend framework (in this example react) you would like to use. Once the command runs simply go to your project folder and install all dependencies.

cd nn-blog
npm install

Then run the dev server with npm run dev. Congratulations, you've just setup a vite + vite-plugin-ssr based project. The setup comes initialized with a git repo, so you can start modifying the code around. And you'll notice how blazingly fast the vite dev server is.

Once you understand the filesystem routing concepts of vite-plugin-ssr, create some pages and experiment. When you're ready let's start with adding mdx-js.

Adding mdx-js to vite project

mdx-js is a library which converts markdown content to jsx compatible content that you can then use with your jsx based libraries such as react, preact, vue.

MDX allows you to use JSX in your markdown content. You can import components, such as interactive charts or alerts, and embed them within your content.
vite uses rollup under the hood to build bundles for production. So for installing mdx-js to a vite project, we should use @mdx-js/rollup and for handling custom MDX components we can use @mdx-js/react for react based projects.

npm install @mdx-js/rollup @mdx-js/react

Once the libraries are installed, add mdx-js to vite plugins in vite.config.js file and config the mdx plugin to use @mdx-js/react as an proiderImportSource.

import react from '@vitejs/plugin-react'
import ssr from 'vite-plugin-ssr/plugin'
+import mdx from "@mdx-js/rollup"

export default {
- plugins: [react(), ssr()]
+ plugins: [react(), mdx({
+   providerImportSource: "@mdx-js/react"
+ }), ssr()],
}

Solving problem 1 - require() of ES Module is not supported

Now after updating the vite.config.js if we try to run npm run dev we'll be given this confusing error

failed to load config from /workspace/example/nn-blog/vite.config.js
/workspace/example/nn-blog/vite.config.js:61509
undefined
            ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /workspace/example/nn-blog/node_modules/@mdx-js/rollup/index.js from /workspace/example/nn-blog/vite.config.js not supported.

This problems occurs in the following order.

npm run dev runs node ./server/index.js file which is a commonjs file
The script creates vite dev server using vite.createServer
The vite dev server converts vite.config.js to CJS module first and then loads the config from this file.
As CJS module tries to require("@mdx-js/rollup") plugin which is a ESM only module the error will be generated.

To solve this problem, we should inform vite to skip building config file to CJS. This can be achieved by adding

+ "type": "module",
}

to package.json file.

Solving problem 2 - require() is not defined in ES module scope

Once we inform node to enable ES modules, we cannot use require syntax in .js files. This is exactly what you'll get when you run npm run dev

file:///workspace/example/nn-blog/server/index.js:1
const express = require('express')
                ^

ReferenceError: require is not defined in ES module scope, you can use import instead
This file is being treated as an ES module because it has a '.js' file extension and '/workspace/example/nn-blog/package.json' contains "type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.

Luckily, the error itself gave us a solution. But you need to first stop scratching your head and learn to read those lines in to identify the solution. If you look carefully what we need is just to rename our index.js file to index.cjs and 💣

Solving problem 3 - Cannot find module

node:internal/modules/cjs/loader:936
  throw err;
  ^

Error: Cannot find module '/workspace/example/nn-blog/server'
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:17:47 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

Wait, where is our file gone? Node says it can't find it, but it's there right in the server folder.

May be if you're patient enough or highly talented nerd enough, you'll understand that node is trying to load server module and not server/index.js. The /index.js file comes into picture as part of the CJS module loading sequence of node. So, we need to add a package.json file with the following value

{
  "main": "index.cjs"
}

And ✨ congratulations, you are now ready to go.

Adding a markdown page

Now go to pages directory and any markdown content with .md or .mdx extention. For example, for creating a /naveennamani root, add pages/naveennamani.page.mdx or pages/naveennamani/index.page.mdx or pages/index/naveennamani.page.mdx file. (I prefer the last filename for this example).

Once you create the file add any markdown content, hit [localhost:3000/naveennamani] url to see your markdown content getting converted into html. For using react components inside your mdx files simply import them and use.

# Hello world

import { Counter } from './Counter'

<Counter />

This will show a heading with an interactive counter that is also shown on home page.

Prerendering and inventing new problems

When you stop the dev server and want to build your awesome website as a static content, you can use vite-plugin-ssr prerender feature. Just add the following script to package.json

"scripts": {
   ...
   "prerender": "npm run build && vite-plugin-ssr prerender"
}

Now when you run npm run prerender, you'll see that dist\client and dist\server folders are created and build files are populated there. But prerendering is failing with

/workspace/example/nn-blog/dist/server/assets/naveennamani.page.04918628.js:4
var react = require("@mdx-js/react");
            ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /workspace/example/nn-blog/node_modules/@mdx-js/react/index.js from /workspace/example/nn-blog/dist/server/assets/naveennamani.page.04918628.js not supported.

Isn't that the same problem we solved earlier? Yes. But why again? 😢
This time the problem is created in the following order.

When you run npm run build it runs vite build and vite build --ssr with the first command building assets for dist\client and second command for dist\server.
While dist\client assets are all esm modules, dist\client build output are cjs modules.
So, again @mdx-js/react which is a ESM only module is failed to import through require.

This time, we can generate ES modules instead of CJS modules by configuring build options in vite.config.js as follows

  import react from '@vitejs/plugin-react'
  import ssr from 'vite-plugin-ssr/plugin'
  import mdx from "@mdx-js/rollup"
+ import { defineConfig } from 'vite'

+ export default defineConfig({
    plugins: [react(), mdx({
      providerImportSource: "@mdx-js/react"
    }), ssr()],
+   build: {
+     rollupOptions: {
+       output: {
+         format: "es"
+       }
+     }
+   }
+ })

When you run npm run prerender again, you can see that dist\server folder contains files which are ES modules. But you still get this complicated error.

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/workspace/example/nn-blog/node_modules/react/jsx-runtime' imported from /workspace/example/nn-blog/dist/server/assets/index.page.0262694b.js
Did you mean to import react/jsx-runtime.js?

Writing a vite plugin to solve our problems

At first sight, the error seems like a spelling mistake. But if you google, there is a long list of comments in the official react repo (issue #20235). The problem can be simply solved by adding .js extension to the import, but how to do that automatically?

Let's write a vite plugin to do that for us. Writing a vite plugin is very simple if you follow the Vite plugin API.

This is what I come with.

export default function fix_ssr_esm_modules(replacements) {
  function transform(code, id, ssr) {
    if (ssr) // ssr is true when `vite build --ssr` is run
      return replacements.reduce((prevCode, { find, replacement }) => {
        return prevCode.replaceAll(find, replacement);
      }, code);
  }

  return { // configuration of our plugin used by vite
    name: "vite-plugin-fix-ssr-esm-modules",
    apply: "build", // execute only for build tasks
    enforce: "post", // execute after build finished
    transform: transform, // transformation function that returns transformed code
  };
}

Now place the code in fix_ssr_esm_modules.js file and then import and use this plugin in vite.config.js file as follows.

+ import fix_ssr_esm_modules from "./fix_ssr_esm_imports.js";

export default defineConfig({
  plugins: [
    react(),
    mdx({
      providerImportSource: "@mdx-js/react",
    }),
    ssr(),
+   fix_ssr_esm_modules([
+     { find: "react/jsx-runtime", replacement: "react/jsx-runtime.js" },
+     { find: "react-dom/server", replacement: "react-dom/server.js" },
+   ]),
  ],
  build: {
    rollupOptions: {
      output: {
        format: "es",
      },
    },
  },
});

The plugin transforms the build files and replaces the import as given as options to the plugin.

Now you can run npm run prerender and serve the files in dist\client statically using npx serve. Congratulations 🌟, you just built a static site using vite-plugin-ssr.

Final touch

The final version of the source code of the project is available in github naveennamani/vite-ssr-mdx.

There is a small inconsistency with server/index.js file, but that's an alternative I found while I'm writing this article.

Sorry for the long post, if you come here after all, here is a potato for you.

My #hacktoberfest2021 honest review

naveennamani — Wed, 03 Nov 2021 08:10:54 +0000

I always love open-source projects for their quality and the amazing community who build it through their contributions. Whenever I'm in need of any professional software for day-to-day productivity or hobby projects for personal use, I always search in google along with "open-source" keyword. I found so many such open-source projects which I end up using very frequently. apps.diagrams.net (formerly draw.io), Greenshot, Mayan EDMS, WinMerge, Notepad++, Visual Studio Code are to name a few.

Early contributions

Even though I use open-source projects, I rarely contribute to them. I often create issues whenever I found problems, but I never go deep into the source-code that I go and solve the issue I just found. But whenever I feel like something can be improved/added without disturbing the existing features, I often tend to work on it.

This is how I made my first contribution in early 2017 in this project jsgif. (The project is not maintained now and my PR is the last commit in the repo). Similarly, I made three more contributions in other projects. However, my biggest contribution was to the project hackingtool #79 where I rewrote the entire project to be more maintainable, uniform and easier to contribute to.

Hacktoberfest 2021

This year, some how I motivated myself to participate in Hacktoberfest 2021 (but 20 days late to the party). It felt difficult to make 4 PRs in 10 days. At the same time, I took it as a challenge.

Finding projects

As I mentioned earlier, I feel comfortable to add something to the project without disturbing the existing code. So, I immediately started searching for projects which are kind of collection of scripts. After going through many projects, I found 4 projects and made some small PRs. As all the projects I contributed to are already popular, there are 100's of pending PRs waiting to be merged.

Waiting...

Being a little impatient, waiting for the PRs to get accepted seems like more challenging than to create the PRs. Some projects have contributing guidelines, and many projects have their own coding preferences, workflows, review/approve users. Some of the things I noticed that are barriers for first-time contributors are

Workflows - for some workflows to run for first-time contributors, maintainers must initiate the workflow. Till then, you won't know if your PR follows the guidelines or if your PR will raise conflicts. Being first time contribution to a project, there are high chances of non-compliance to the guidelines.
Changes and review process - If maintainers propose changes, you've to go through the "Change"->"Push"->"Request for Review"->"Wait" cycle. If the maintainers who were asked for review are not active while no other maintainers looks at your PR as they're not assigned, the delay in merging the PR will be more.

Small projects to the rescue

While popular projects with so many maintainers, workflows and guidelines attracts you to contribute, the real satisfactory contributions will always belong to small unpopular projects. As I was waiting for my 4 PRs while they're in the "reviewing/neglected" state, I found this project react-tailwind-portfolio which I contributed to and got my first ever "hacktoberfest-accepted" label within 24Hrs of finding the project.

Finally done with 4 PRs

After my first PR, 3 out of the earlier 4 PRs are merged and I finished my #hacktoberfest challenge. As I was writing this post, one of my PR is still waiting to be merged :(.

Takeaways and suggestion to my future self

Always try to contribute to small projects
Create issue first and work on the PR
Try to solve the existing issues by diving into the code
Create a project which others wants to contribute to :)

Thanks for reading.

Naveen Namani

Offline documentation of tailwindcss in 5 easy steps

naveennamani — Sun, 10 Oct 2021 17:20:29 +0000

This post is a 2nd one in the Offline documentation series. If you're new here check out my first post.

Generate offline documentation of reactjs in 5 minutes

For more scripts like this, please visit my offline-docs github repo currently contains more than 30 scripts.

In this post, let's build the offline documentation for tailwindcss, my favorite utility first CSS framework, and my go to CSS framework for rapidly prototyping a design.

Getting the source code

The documentation for tailwindcss is available on tailwindcss.com website. We can easily find the source code for this website on github through a simple google search. It is hosted on github at https://github.com/tailwindlabs/tailwindcss.com.

Let us first download the source code and inspect.

git clone https://github.com/tailwindlabs/tailwindcss.com
cd tailwindcss.com

Open the code editor of your choice. If using vscode, just enter

code .

Understanding the tech stack

If we look at the files in the root directory, we can understand that

next.config.js - The website is written in nextjs
tailwind.config.js - The website is build using tailwindcss as the CSS framework (what else you expect?)
yarn.lock - using yarn as the package manager

For understanding the deployment process of nextjs, we can simply go to its corresponding documentation website. You can find the information in below links.

package.json

Once you gain enough info on how deployment works, let's open package.json file and see if we have the required scripts already present. Luckily, we have the script export for generating static files. Our life has been made easier already.

Commands

Now we have enough information to generate the documentation.

Install all the dependencies using the yarn package manager.
```
yarn install
```
Run the build script using
```
yarn export
```
This will generate the required static HTML, js, css and all assets in the out folder.

Serve the documentation generated in out folder

cd out
python -m http.server // simpler
// Or if you prefer nodejs
yarn global add serve
serve

Congratulations! We now have tailwindcss documentation available offline.

If you would like to have offline documentation for any framework/library you require, please tell us in the comments.

Pro tip for vscode users

jsconfig.json

If you have the following directory structure

Home
\- components
   |- A.js
   |- B.js

utils
\- utils.js

and want to import utils.js in A.js, you need to use relative paths as follows

import utils from "../../utils/utils.js"

This makes it harder to follow the file being imported, and once you have a folder structure 3 or more levels deep, this makes it even harder to write the required imports keeping in mind all the folders.

jsconfig.json to the rescue!

You can use "compilerOptions" > "paths" dictionary to define the path mappings relative to the root of the project.

{
    "compilerOptions": {
        "paths": {
            "@/utils/*": ["utils/*"],
            "@/home/*": ["Home/components/*"]
         },
    }
}

Now instead of all those relative paths to import utils, you can simply use

import utils from "@/utils/utils.js"

to import the utils, and to import A.js in any other file, we can write

import A from "@/home/A.js"

You can see this jsconfig.json file being used in the tailwindcss.com project. Go inspect the source code and have fun learning new things.

Happy coding!

Generate offline documentation of reactjs in 5 minutes

naveennamani — Sat, 09 Oct 2021 13:35:27 +0000

When it comes to learning a new language, framework or library, the first and important source of help comes from the documentation provided by the respective websites. But it is often difficult to go through the complete documentation immediately. And during development we need to refer to the documentation very frequently.

Having an offline version of the documentation may help to find the information faster and whenever required. Also, it helps to work offline without any distractions from the facebook notifications.

In this post, let's build the offline documentation for reactjs.

Getting the source code

The documentation for reactjs is available on reactjs.org website. The source code for this website is available as a github repository here.

Fireup a cmd, clone this repository and cd into the directory



git clone https://github.com/reactjs/reactjs.org
cd reactjs.org

Open the code editor of your choice. If using vscode, just enter



code .

Understanding the tech stack

Once we have the source code, we can see many configuration files there. The most important ones that quickly gives us all the information we need are

gatsby-*.js - these files tells us that Gatsby is used for generating the static HTML for the website.
yarn.lock - it is using yarn as the package manager.
vercel.json - the website is hosted on vercel

package.json

Perhaps, package.json is the one file that any webdev will start looking at when they start working on a new project. Once we open this file, we can see the dependencies of the projects and the scripts used.

From the file we can see the following scripts.

Luckily, we have the build script that we require to build the static HTML.

Commands

Now we have enough information to generate the documentation.

Install all the dependencies using the yarn package manager. ```bash

yarn install

1. Run the build script using
    ```bash


yarn build

This will generate the required static HTML, js, css and all assets in the **public** folder.

Serve the documentation generated in public folder ```

cd public
python -m http.server // simpler
// Or if you prefer nodejs
yarn add global serve
serve


**Congratulations!** We now have reactjs documentation available offline.

If you would like to have offline documentation for any framework/library you require, please tell us in the comments.

Happy coding!