Skip to content

Commit

Permalink
Update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@willybrauner
willybrauner committed Feb 28, 2024
1 parent 18df68a commit 1dce107
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 178 deletions.
14 changes: 3 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<h1 align="center" style="text-align:center">🪜 chersite</h1>

<p align="center">
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.

<br/>
<br/>
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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
Expand Down
223 changes: 56 additions & 167 deletions apps/front/README.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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:

### <a name="BemForModuleScss"></a>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 {
}
}
```

### <a name="BemForLess"></a>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.
Expand Down

0 comments on commit 1dce107

Please sign in to comment.