Skip to content

๐Ÿš€ Start UI [web] is an opinionated UI starter with โš›๏ธ React, โ–ฒ NextJS, โšก๏ธ Chakra UI, โš›๏ธ TanStack Query & ๐Ÿœ Formiz โ€” From the ๐Ÿป BearStudio Team

License

BearStudio/start-ui-web

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
January 21, 2021 09:25
December 22, 2022 16:39
src
May 30, 2023 13:09
May 25, 2023 13:34
January 19, 2021 09:55
October 28, 2021 14:18
May 25, 2023 13:34
July 12, 2021 14:52

Start UI Web

Discord

๐Ÿš€ Start UI [web] is an opinionated frontend starter repository created & maintained by the BearStudio Team and other contributors. It represents our team's up-to-date stack that we use when creating web apps for our clients.

Documentation

For detailed information on how to use this project, please refer to the documentation. The documentation contains all the necessary information on installation, usage, and some guides.

Demo

A live read-only demonstration of what you will have when starting a project with ๐Ÿš€ Start UI [web] is available on demo.start-ui.com.

Getting Started

npx create-start-ui@latest --web myApp

That will scaffold a new folder with the latest version of ๐Ÿš€ Start UI [web] ๐ŸŽ‰

Then just go to the created folder:

cd myApp
# Duplicate the .env.example file to a new .env file (update variables)
cp .env.example .env

# Init the local mocks database and seed users
yarn db:push && yarn db:seed

# Run the development server
yarn dev

Technology

๐Ÿ‘‰ Technology Choices

โ„น๏ธ API calls are mapped on a JHipster backend application.

Features

You can find more details about each feature on the documentation

  • Reponsive layout / navigation.
  • Sign In / Sign Up / Password recovery screens.
  • Account profile / Change Password screens.
  • Users management admin screens (CRUD).
  • Multi-languages (i18n) (English & French built-in).
  • Custom Chakra UI theme with generated typings.
  • Great list of UI components with their Storybook documentation.
  • Fields components for Formiz.
  • Dark mode support with Storybook toggle.
  • App version & Environment name in the UI.
  • API Schema documentation via Swagger UI React.
  • API Mocking with a JHipster mapping using Next.js API.
  • Developer eXperience improved with ESLint, Prettier and Husky
  • Deployment made easy using Next.js

Installation

  1. Duplicate the .env.example file to a new .env file, and update the environment variables
cp .env.example .env
  1. Install dependencies
yarn install
  1. Init the local mocks database and seed users
yarn db:push && yarn db:seed

Development

# Run the development server
yarn dev

Storybook

yarn storybook

Update theme typing

When adding or updating theme components, component variations, sizes, colors and other theme foundations, you can extend the internal theme typings to provide nice autocomplete.

Just run the following command after updating the theme:

yarn theme:generate-typing

Generate custom icons components from svg files

Put the custom svg files into the src/components/Icons/svg-sources folder and then run the following command:

yarn theme:generate-icons

โš ๏ธ All svg icons should be svg files prefixed by icon- (example: icon-externel-link) with 24x24px size, only one shape and filled with #000 color (will be replaced by currentColor).

Development with a JHipster backend

Update the NEXT_PUBLIC_API_BASE_URL with your JHipster API url:

NEXT_PUBLIC_API_BASE_URL="http://localhost:8080/api"

Show hint on development environments

Setup the NEXT_PUBLIC_DEV_ENV_NAME env variable with the name of the environment.

NEXT_PUBLIC_DEV_ENV_NAME="staging"
NEXT_PUBLIC_DEV_ENV_COLOR_SCHEME="teal"

Translations

Setup the i18n Ally extension

We recommended using the i18n Ally plugin for VS Code for translations management.

Create or edit the .vscode/settings.json file with the following settings:

{
  "i18n-ally.localesPaths": ["src/locales"],
  "i18n-ally.keystyle": "nested",
  "i18n-ally.enabledFrameworks": ["general", "react", "i18next"],
  "i18n-ally.namespace": true,
  "i18n-ally.defaultNamespace": "common",
  "i18n-ally.extract.autoDetect": true,
  "i18n-ally.keysInUse": ["common.languages.*"]
}

Guidelines for translations

  • Use namespaces t('namespace:translationKey') and nesting t('namespace:this.is.nested').
// Example for translations available in account.json
t('account:data.firstname.label')
  • For fields and data translations use a data object.
// account.json
{
  "data": {
    "firstname": {
      "label": "First Name",
      "required": "First Name is required",
    },
  }
}
// React
t('account:data.firstname.label')
t('account:data.firstname.required')
  • For user feedbacks, use a feedbacks object with actionSuccess & actionError keys containing each title and description (optional).
// account.json
{
  "resetPassword": {
    "feedbacks": {
      "resetSuccess": {
        "title": "Your password has been reset",
        "description": "You can now login"
      },
      "resetError": {
        "title": "Reset password failed"
      }
    }
  }
}
// React
t('account:resetPassword.feedbacks.updateSuccess.title')
t('account:resetPassword.feedbacks.updateSuccess.description')
t('account:resetPassword.feedbacks.updateError.title')
  • For user actions, use an actions object.
// account.json
{
  "resetPassword": {
    "actions": {
      "send": "Send Email",
      "reset": "Reset Password"
    }
  }
}
// React
t('account:resetPassword.actions.send')
t('account:resetPassword.actions.reset')
  • Use the common workspace only for VERY generic translations. By default, use specific namespaces to allow easy update on large code base without unwanted side-effects.

Production

NodeJS (recommended)

yarn install
yarn storybook:build # Optional: Will expose the Storybook at `/storybook`
yarn build
yarn start

Docker

  1. Build the Docker image (replace start-ui-web with your project name)
docker build -t start-ui-web .
  1. Run the Docker image (replace start-ui-web with your project name)
docker run -p 80:3000 start-ui-web

Application will be exposed on port 80 (http://localhost)

Static files

Update the next.config.js file with output: 'export' (and remove redirects and rewrites)

{
  output: 'export',
}
yarn storybook:build # Optional: Will expose the Storybook at `/storybook/`
yarn build

Then expose the /out folder.

You can use yarn build && npx serve out -c ../static.serve.json to build and run the static build locally.

๐Ÿ’ก You will need to setup your server to rewrite all /app/* urls to serve the app.html file.

Using Apache as your web server

If you are using apache to statically deploy your app, you can use the following configuration for public/.htaccess :

# public/.htaccess
Options -MultiViews
RewriteEngine On

# Rewrite /app/* to app.html
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule "^app/" "app.html" [QSA,L]

Technology Choices

React

React is a JavaScript library created in 2013 to build reactive user interfaces. At the time of writing, React is probably the front end library the most used to create new projects and has a huge community which is beneficial for the maintainability of the project in terms of developers and online resources.

GitHub ยท License MIT

Next.js

Next.js gives you the best developer experience with all the features you need for production: hybrid static & server rendering, TypeScript support, smart bundling, route pre-fetching, and more. No config needed.

GitHub ยท License MIT

React Router

Next.js is bundled with its own router, but at the time of writing those lines, it does not allow SPA mode.

GitHub ยท License MIT

TypeScript

JavaScript is a not typed language. TypeScript is here to help add static type definition. TypeScript helps a lot when it comes to types, interfaces and define contract between functions which helps a lot for a reliable documentation. No worry, the TypeScript adoption is incremental and writing in TypeScript is not mandatory to use Start UI, but it is a good practice to do so to avoid bugs in the future.

GitHub ยท License Apache 2.0

TanStack Query

TanStack Query is a powerful tool to do efficient data synchronization for React. No need of Redux or another global state manager anymore. Usable with fetch, axios, or graphql-request, React Query will do the work and is agnostic of the method you will use.

GitHub ยท License MIT

Storybook

Storybook is an Open Source tool to help you develop framework agnostic components in isolation and document them.

GitHub ยท License MIT

Chakra UI

Chakra UI is a simple, modular, composable and accessible component library that is highly customizable.

GitHub ยท License MIT

Formiz

To create React forms, there is a lot of libraries out there. Formiz will help you create React forms with ease! Composable, headless & with built-in multi steps.

GitHub ยท License MIT

Cypress

Cypress is a tool for end-to-end, component and unit test

Cypress ยท License MIT

About

๐Ÿš€ Start UI [web] is an opinionated UI starter with โš›๏ธ React, โ–ฒ NextJS, โšก๏ธ Chakra UI, โš›๏ธ TanStack Query & ๐Ÿœ Formiz โ€” From the ๐Ÿป BearStudio Team

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks