@basaldev/blocks-frontend-framework

blocks-frontend-framework

❤️

What is this?

The Nodeblocks Framework is a library which provides scaffolding for building Nodeblocks frontend React applications. Using this framework, you can quickly build a frontend application made up of multiple Nodeblocks blocks, composed together using a standardized architecture.

🏗 Project Structure

.
├── .github
├── .husky                 # husky settings - @basaldev/lint-staged-config
├── .vscode                # vscode settings
├── .yarn                  # yarn binary, config and project dependencies
├── coverage *             # jest coverage report
├── dist *
├── docs
├── public                 # files that will be exported to npm (e.g. svg and other images)
├── src
│   ├── design-system      # Design system components
│   │   ├── basic
│   │   ├── composite
│   ├── examples           # Example applications (used for testing locally)
│   ├── framework
│   │   ├── app
│   │   ├── block
│   │   ├── template
│   │   └── types.ts
│   └── index.ts
├── .eslintignore
├── .eslintrc.js            # @basaldev/eslint-config
├── .gitignore
├── .nvmrc
├── .pnp.cjs                # yarn config
├── .pnp.loader.mjs         # yarn config
├── .prettierignore
├── .prettierrc.json        # @basaldev/prettier-config
├── .yarnrc.yml             # yarn config
├── cspell.config.js        # @basaldev/cspell-config
├── .yarnrc.yml             # yarn config
├── index.html              # Example application index.html
├── package.json
├── README.md
├── tsconfig.json           # @basaldev/tsconfig
├── vite.config.ts          # Vite configuration for building and running the project
└── yarn.lock

🔰 Starting a new project using frontend-framework

• Create a new repository on github
• Create a new vite project using the react-ts template. See here for instructions.
• Import the npm package @basaldev/blocks-frontend-framework into your project
• Copy one of the appropriate examples from src/examples into your project root (Note that you will need to copy examples/core-styles.css as well to configure the base styles for the application)
• TODO: Add instructions for importing the application

Customizing CSS and themes

The framework uses CSS modules to scope styles to each component, as well as CSS variables that can be used to configure the framework.

🔰 Contributing Setup

Create a Github Personal Auth Token

• Go to Github Developer Settings > Personal Tokens > Generate new token
• Click 'Generate Token'
• Input a name for your token.
• Select repo checkbox
• Select write:packages
• Add to your local environment - .zshrc .bashrc etc

export NODEBLOCKS_DEV_TOKEN=__INSERT_YOUR_TOKEN_HERE__

Install NVM

• OSX / Linux
• Windows

Install Yarn (Global)

Yarn must be installed globally for the project's NodeJS version. This should be done so using the command below.

nvm use && npm install -g yarn

Install Husky 🐺

yarn dlx husky init

⚠️ IMPORTANT: Only use the yarn command install or run scripts. Do not use npm run xxx

🪄 Usage

Run vite

First, create a .env file in the root of the project:

cp .env.example .env

Fill this .env file with the appropriate URLs for the backend services.

Second, create a local https cert

brew install mkcert
mkcert -install
mkcert localhost

Then, run the following command to start the vite server

yarn dev

By default, the vite server will use the hello-world example. To use a different example, run the following command:

APP_TYPE=example-folder yarn dev

(Generally, instead of this, you will want to yarn link a separate project that uses the framework.)

Run storybook

yarn storybook

Run unit tests

yarn test

Installing packages

yarn add <package> | yarn add <package> -D

Linking local packages for local testing

To add blocks-frontend-sdk, run this yarn command first:

yarn link /full/absolute/path/to/blocks-frontend-sdk

Then, add this to vite.config.ts:

export default defineConfig({
  ...
  optimizeDeps: {
    include: ['@basaldev/blocks-frontend-sdk'],
  },
  ...
});

⚡️ Special Notes for VSCode Users

📐 Required Extensions

Please ensure the following extensions are installed:

• arcanis.vscode-zipfs
• dbaeumer.vscode-eslint
• seatonjiang.gitmoji-vscode
• henrynguyen5-vsc.vsc-nvm (optional)

🛠 Workspaces

The kit uses vscode workspaces for vscode project settings:

• All common vscode project settings should be specified in the .vscode/${project_name}-workspace file.
• Personal user settings should be added to .vscode/settings.json (gitignored)
• ⚠️ You must open this project as a workspace in vscode This can be done by clicking the workspace file while in vscode, or by using File > Open workspace from file.

🪛 TypeScript

When prompted asking which typescript VSCode should use, it's very important that you choose the local project version located at .yarn/sdks/typescript/...

💅 Prettier

If you have the prettier extension installed, please disable it for this project. ts-kit uses eslint to execute prettier, so having prettier enabled in vscode will cause conflicts and strange behavior.

🤖 Format on Save (optional)

Add the following code to your .vscode/settings.json will automatically fix all eslint errors whenever you save a file.

  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }

🚀 Package Deployment

This library uses github registry to publish private npm package. For detailed instructions see here

💡 Note: that npm is used for version & publish commands

1. Bump version

npm version ${VERSION}

2. Build Package

yarn build

3. Publish Package

npm publish

Then go to github https://github.com/basaldev/blocks-frontend-sdk/packages to check published packages.