Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update doc #180

Merged
merged 1 commit into from
Feb 28, 2024
Merged

Update doc #180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 3 additions & 11 deletions README.md
View file
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,175 +1,118 @@
# Chersite front app

- [About](#about)
- [Builds](#builds)
- [SSR build](#SSR-build)
- [SSG build](#SSG-build)
- [SPA build](#SPA-build)
- [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 build

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 build

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 build

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
Loading