vite-rio-template

Summary

This is the RIO TypeScript template for building new RIO services based on Vite as build tooling.

How to create a new project

Create a new service app with this template via degit:

npx degit rio-cloud/vite-rio-template my-rio-service-web

Or clone the project manually.

How to configure your new project

• Copy the .env.development into a .env.local for your local config and adapt it to your needs.

• Update the package.json to set the application name and use that name also for the license_check script.

• Optional: Change the dev server port in vite.config.ts to your likings. In case you change it, don't forget to update it in the package.json for the cypress-ci script as well as in your .env.local config.

• Production configuration

  • Request a Sentry token to use Sentry in production. Add it to the .env.production config file.
  • Define the redirect url for your service in .env.production.
  • Request and supply your App's client_id as well as the needed OAuth scopes in src/config.ts.

---

Tech Stack

The RIO template is opinionated and comes already with some pre-defined libraries to give you a head start and streamline the various projects so devs feel familiar when working with multiple projects. If you still want to use something else, feel free to remove or adapt the sample implementations.

• Build Tooling:
  • Vite - that uses esbuild and Rollup under the hood
• Frontend Library:
  • React
• Routing:
  • React Router
• State Management:
  • Redux Toolkit
• Data Fetching:
  • RTK Query since it is within the same ecosystem as Redux
• UI component library:
  • RIO UIKIT
• Form validation
  • React Hook Form
• Testing
  • Jest as test runner and testing framework for unit tests
  • Testing Library as the testing utility
  • Cypress as integration, end-to-end, monitoring test suite
• API Mocking:
  • MSW mock API calls by intercepting requests on the network level. This can be used for development and testing alike.
• Localization:
  • react-intl as I18n library
  • Phrase managing translations. To fetch translations, the Phrase CLI is used
• Service Monitoring and Issue Tracking:
  • Sentry
• Static code analysis and formatting:
  • ESLint
  • Prettier for autoformatting source code

Folder Structure

A short explanation of what each folder is meant for:

• src
  • components: All service-specific components that are used multiple times across the service. These components are generic and reusable. They do not relate to a certain feature. Imagine a custom input component with validation that is used in various features for example in different forms.
  • configuration: Service configuration like login, token handling, language settings, or general setup files like the redux store
  • data: All relevant files for data definition to be used for the service; i.e. table configuration; initial service data or configurations, date formatter, currencies, etc.
  • features: The folder for all feature-relevant things. Each feature is meant to be in a dedicated subfolder that colocates feature-relevant files. Examples are header, sidebars, maps, trees, user lists, tables, forms, etc. Features are rather isolated and don't interact with other features. This way, they are easy to replace, remove, or change. Features are combined on pages.
  • hooks: All custom hooks used across the project
  • layout: The folder for the overarching layouts as defined in App.tsx
  • pages: The folder for all navigatable service pages. Pages are composed of features and components. For the Frontend template, these are the "intro" and "more" pages. It actually represents, what is defined in the header as routes. But this could also be sub pages in some cases.
  • routes: All route-related files like route definitions, route updater, route hooks etc.
  • services: All service API connections, redux-toolkit-query APIs or thunks, io-ts converter, model types, etc.
  • utils: Common utility files and functions
• tests
  • integration: all cypress integration tests
  • utils: utility functions that are used in integration tests

Note, there is no dedicated root folder for all the type files on purpose, as we believe that the typings should be colocated to the files where they originate from. This means, that component types belong to the respective component folder, model types belong to the respective API in the service folder, etc.

Migrate existing projects to Vite

• Add vite dependencies to jour project

  npm i -D vite @vitejs/plugin-react babel-plugin-transform-vite-meta-env rollup-plugin-visualizer events
  

• Remove old dependencies

  npm uninstall react-scripts react-app-rewired source-map-explorer webpack webpack-bundle-analyzer webpack-cli webpack-dev-server @webpack-cli/init html-webpack-plugin compression-webpack-plugin babel-loader css-loader less-loader file-loader html-loader raw-loader script-loader style-loader url-loader ts-loader less mini-css-extract-plugin
  

• Copy vite.config.ts to your project
• Update package.json scripts
  • Remove script eject as this is no longer needed
  • Update scripts start, build and test accordingly to use vite

  "start": "vite",
  "build": "tsc && vite build",
  "preview": "vite preview",
  "test": "jest src",
  

• Move the index.html out of the public folder into the root.
  • Adapt the entry point for your index.tsx file to: <script type="module" src="/src/index.tsx"></script>
  • Remove the public folder
  • Adapt the CICD scripts accoringly
• Remove analyze script for not using "source-map-explorer" but rather "rollup-plugin-visualizer". Later is already configured in vite.config.ts
• Replace node environment variables with vite imports
  • process.env.REACT_APP_* to import.meta.env.VITE_*
  • process.env.NODE_ENV !== 'production' with import.meta.env.DEV
• Rename REACT_APP_* config variables to VITE_*
  • Update .env.production and .env.development file as well as src/config.ts plus all occurences in your code
• Copy the .env.development into a .env.local for your local config.
• Add files to your .gitignore

  .local
  .env
  stats.html
  

• Remove your old webpack.config.js and all related files
• Rename .js or .ts files to .jsx or .tsx in case they are React components and contain JSX syntax
• In case you have custom CSS in one or more .less files, you might need to add the entry to your index.ts by adding a dedicated import of your main .less file
• In case you'll face an error message like "Request url is outside of Vite serving allow list", you might want to add the following to your vite.config:

  export default defineConfig({
      // ....
      server: {
          // ....
          fs: {
              strict: false,
          },
      },
  });
  

• Optionaly, change default port to your old project settings by editing the vite.config.tsand add the server.port

  export default defineConfig({
      // ....
      server: {
          // ....
          port: 8090,
      },
  });
  

• In case you use react-router v5, you might update the history package to min v5.3.0
• Recommended: Adapt the project folder structure to the template folder structure. This will ensure that developers feel right at home when working with your project and other projects.