-chersite is multi apps structure witch include a SSG/SSR front framework for cher-ami projects
+chersite is multi apps structure witch include a SPA/SSG/SSR front framework for cher-ami projects.
@@ -30,7 +30,7 @@ Each app has his own `package.json` and `node_modules` folder, we build them sep
### Front app
-The front app is a React static-site generator build with [vite](https://vitejs.dev/), [react](https://reactjs.org/),[typescript](https://www.typescriptlang.org/), and [sass](https://sass-lang.com/), in order to obtain a static server rendering for best performance. The build step prepare a server script, a prerender script and a SPA version to leave choice of use. This one embeds [@cher-ami/router](https://github.com/cher-ami/router) to manage server static props, routes transitions and languages.
+The front app is a React SPA/SSG/SSR builder, scaffold with [vite](https://vitejs.dev/), [react](https://reactjs.org/),[typescript](https://www.typescriptlang.org/), and [sass](https://sass-lang.com/) with [@cher-ami/router](https://github.com/cher-ami/router) on top.
See the [front app documentation](apps/front/README.md)
@@ -131,18 +131,10 @@ Scaffold a new React component called `MyButton` in [apps/front/src/components](
Options are defined from [cli/config.js](cli/config.js):
```js
-bundleType: ["react", "dom"]
+bundleType: ["react"]
componentCompatibleFolders: ["components", "pages"]
```
-### back:scaffold-wp
-
-```shell
-npm run back:scaffold-wp
-```
-
-Scaffold Page, Post type, Option pages for Wordpress.By default, it will create files in `apps/back/web/app/themes/CherAmi/`.
-
## Scripts
### Update app version
diff --git a/apps/front/README.md b/apps/front/README.md
index 9691d3d..9602be5 100644
--- a/apps/front/README.md
+++ b/apps/front/README.md
@@ -1,175 +1,118 @@
# Chersite front app
- [About](#about)
+- [Builds](#builds)
+ - [SSR](#SSR)
+ - [SSG](#SSG)
+ - [SPA](#SPA)
- [Entry points](#entry-points)
- [Configuration Files](#configuration-files)
-- [Prerender](#prerender)
- [CLI](#cli)
-- [Vite plugins](#vite-plugins)
- [Setup local SSL](#setup-local-ssl)
-- [Workflow](#workflow)
## About
-This front app is a React SSG/SSR framework. It run with [vite](https://vitejs.dev/), [react](https://reactjs.org/),[typescript](https://www.typescriptlang.org/), and [scss](https://sass-lang.com/). The build step prepare a server script, a prerender script and a SPA version to leave choice of use. This one embeds [@cher-ami/router](https://github.com/cher-ami/router) to manage server static props, routes transitions and languages.
+Chersite front app is a React SPA/SSG/SSR framework, built with [vite](https://vitejs.dev/), [react](https://reactjs.org/),[typescript](https://www.typescriptlang.org/), [sass](https://sass-lang.com/) and [@cher-ami/router](https://github.com/cher-ami/router) on the top.
-## Entry points
-
-Two entry points are set:
+## Builds
-- server side [src/index-server.tsx](src/index-server.tsx)
-- client side [src/index-client.tsx](src/index-client.tsx)
+When chersite is built, it automatically creates three types of apps. It allows you to choose to use the one that best suits the type of project.
-## Configuration Files
+### SSR
-Vite's configuration is managed by two main files:
-
-- [vite.config.ts](vite.config.ts): contains the whole vite config [(vite config documentation)](https://vitejs.dev/config/)
-- [vite.scripts.config.ts](vite.static-scripts.config.ts): contains the whole vite scripts config. It built scripts files relative to the SSR and SSG part.
-- [config/config.js](config/config.js): is the internal paths and tasks config file.
+The SSR app provides a `server.prod.js`, to run on production. The client code will hydrate the server response on the fly.
-## SSR
+Output:
-The app is SSR ready:
+```
+dist/
+ - ssr/
+ - client/ ← SSR client code
+ - scripts/ ← contains the server.prod.js for stating the SSR app with "npm run start"
+```
```shell
-npm run build && npm run start
+npm run build:ssr && npm run start
```
-## SSG
+### SSG
-chersite front allows to generate a static site. The prerender script is used to generate static html files from the server side.
+chersite front allows to generate a static HTML files with `prerender`.
-The "prerender" fonction need to know the list of routes to generate as static html files.
+the main thinks to consider is, the `prerender` fonction needs to know the list of routes to generate as static html files.
You have to list manually all routes you want to prerender in [prerender/urls.ts](prerender/urls.ts):
```ts
return new Promise((resolve) => {
resolve([
- "/",
- // will generate /work/index.html (because "/work/other-route" exists in the list)
- "/work",
- // will generate /work/first-work.html
- "/work/first-work",
- // duplicate route with lang if the router is configured on this way
- "/fr",
- "/fr/work",
- "/fr/work/first-work"
+ "/", // → /index.html
+ "/work", // → /work/index.html
+ "/work/first" // → /work/first.html
])
})
```
⚠️ **The front application routing is not linked to the generated html files, so you can add any route you want in
-this list**. In case you use a backend, you will have to get all routes from a backend API call and add them in this list.
+this list**. In case you use a backend, you will have to get all routes from a backend API call and add them in this list too.
By default, the generate command is executed on build step, but you can run it manually:
```shell
-npm run generate
+npm build:static
```
-## CLI
-
-- [dev](#dev)
-- [build](#build)
-- [generate](#generate)
-
-npm scripts command line interface is available from the main [package.json](./package.json).
-Each script can be executed from `npm run {task}` command.
+Output:
-### dev
-
-```shell
-$ npm run dev
```
-
-Start a dev-server with HMR.
-
-### build
-
-```shell
-$ npm run build
+dist/
+ - static/
+ - client/ ← static page generated client code
+ - scripts/ ← contains prerender.js and exe-server-prerender.js used to execute generate task
```
-Build script in selected [config/config.js](config/config.js) `outDir`
-
-### generate
+### SPA
-Generate static html files from the server side.
+The single page application can be useful in some case (embedded sites for example) but not the best choice for SEO.
```shell
-npm run generate
+npm run build:spa
```
-### start
-
-Start the production server for SSR
+Output:
-```shell
-npm run start
+```
+dist/
+ - spa/ ← single page application
```
-## Vite plugins
-
-By default, chersite implement:
-
-plugins:
-
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc)
-- [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy)
-- [vite-plugin-checker](https://github.com/fi3ework/vite-plugin-checker)
-
-Custom plugins:
-
-- [vite-plugin-build-dotenv.ts](config/vite-plugins/vite-plugin-build-dotenv.ts)
-- [vite-plugin-build-htaccess.ts](config/vite-plugins/vite-plugin-build-htaccess.ts)
-
-### Vite plugin build dotenv
-
-[vite-plugin-build-dotenv.ts](config/vite-plugins/vite-plugin-build-dotenv.ts)
-fields the need to expose, in a `.env` file, external environment variables injected into
-process.env by the CI or another task; In addition to the .env files corresponding to the current
-[mode](https://vitejs.dev/guide/env-and-mode.html).
-Once a new file is composed, it is copied to the selected folder(s).
-
-.env out directory(ies) array is defined from [config/config.js](config/config.js):
+## Entry points
-```js
-buildDotenvOutDir: [resolve("dist/")]
-```
+There is two entry points on the app. Both can be edited, depends of usage
-This plugin is mandatory for the use of the default cher-site config with the PHP micro framework.
+- server side [src/index-server.tsx](src/index-server.tsx): Contains the root tree of the application.
+- client side [src/index-client.tsx](src/index-client.tsx): Contains the client root app witch hydrate the server-side DOM rendering, or create a new root for SPA.
-### Vite plugin build htaccess
+## Configuration Files
-[vite-plugin-build-htaccess.ts](config/vite-plugins/vite-plugin-build-htaccess.ts)
-will copy an .htaccess template in a selected directory.
+Vite's configuration is managed by:
-Options are available in [.env](.env):
+- [vite.config.ts](vite.config.ts): contains the whole vite config [(vite config documentation)](https://vitejs.dev/config/)
+- [vite.ssr-scripts.config.ts](vite.ssr-scripts.config.ts): contains the whole vite scripts config. It built scripts files relative to the SSR.
+- [vite.static-scripts.config.ts](vite.static-scripts.config.ts): contains the whole vite scripts config. It built scripts files relative to the static generator.
+- [config/config.js](config/config.js): contains the internal paths.
-This plugin can scaffold a `.htpasswd` linked to the generated `.htaccess` file.
-It's useful to add password on specific environment deployment.
+## CLI
-```.dotenv
-# Buid .htaccess file from template
-BUILD_HTACCESS=true
-# Build .htpasswd allow to create htaccess password to specific domaine
-HTACCESS_ENABLE_AUTH=false
-# Plain text user. ex: "staging"
-HTACCESS_AUTH_USER=
-# Encrypted password @generator: https://www.web2generators.com/apache-tools/htpasswd-generator
-HTACCESS_AUTH_PASSWORD=
-# ex: "var/www/"
-HTACCESS_SERVER_WEB_ROOT_PATH=
-# Redirect http to https
-HTACCESS_ENABLE_HTTPS_REDIRECTION=false
-```
+npm scripts command line interface is available from the main [package.json](./package.json)
-Second part of the configuration is defined from [config/config.js](config/config.js):
+`npm run ...`:
-```js
-htaccessTemplateFilePath: resolve("src/.htaccess")
-```
+- `dev` - start dev-server
+- `build:spa` - build spa website type
+- `build:ssr` - build SSR website type
+- `build:static` - build static website type
+- `build` - build all website's types
+- `start` - run the SSR prod server
## Setup local SSL
@@ -193,60 +136,6 @@ htaccessTemplateFilePath: resolve("src/.htaccess")
When you run `npm run dev`, you should see the app running on https://localhost:5173
-## Workflow
-
-### CSS workflow
-
-[sass](https://sass-lang.com) is used as css preprocessor. It can be set as `.less` file or `.module.less` for css module;
-Both works by default.
-
-[BEM methodology](http://getbem.com) is used to organize the integration of our templates and components
-but have some differences depend on the use-case:
-
-### BEM for `.module.scss`
-
-```scss
-/**
- * BEM block is always "root" className
- */
-.root {
-}
-/**
- * BEM element (.camelCase)
- */
-.myButton {
- /**
- * BEM modifier (&_camelCase)
- * sep with "_" allows to target it from template like this: "css.myButton_myModifier"
- */
- &_red {
- }
-}
-```
-
-### BEM for `.scss`
-
-```scss
-/**
- * BEM block (.PascalCase)
- */
-.Component {
- /**
- * BEM element (.camelCase)
- usage: "Component_myElement"
- */
- &_myElement {
- /**
- * BEM modifier (&_camelCase)
- * sep with "_" allows to target it from template
- * usage: "Component_myElement-myModifier"
- */
- &-red {
- }
- }
-}
-```
-
## Credits
Developed by [cher-ami](https://github.com/cher-ami) team.