Skip to content

Commit

Permalink
docs: add documention website
Browse files Browse the repository at this point in the history
  • Loading branch information
@hemengke1997
hemengke1997 committed Nov 6, 2024
1 parent 1382241 commit a9e02e0
Show file tree
Hide file tree
Showing 32 changed files with 3,494 additions and 1,666 deletions.
63 changes: 37 additions & 26 deletions .github/workflows/pages.yml
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,51 @@
name: Github Pages Deploy
name: Deploy VitePress site to Pages

on:
push:
branches:
- master
branches: [master]

workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: true
cancel-in-progress: false

jobs:
deploy:
if: contains(github.event.head_commit.message, 'release') || contains(github.event.head_commit.message, 'deploy')
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
uses: actions/checkout@v4
- uses: pnpm/action-setup@v3
- name: Setup Node
uses: actions/setup-node@v4
with:
persist-credentials: false

- name: Install pnpm
uses: pnpm/[email protected]
node-version: 20
cache: pnpm
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: pnpm i
- name: Build with VitePress
run: npm run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
version: 8.7.0

- name: Install Dependencies
run: |
pnpm install
path: docs/.vitepress/dist

- name: Build
run: |
pnpm run build:pages
- name: Deploy
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.GHB_TOKEN }}
BRANCH: gh-pages
FOLDER: playground/spa/dist
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
2 changes: 0 additions & 2 deletions .github/workflows/publish.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,6 @@ jobs:

- name: Install pnpm
uses: pnpm/[email protected]
with:
version: 8.7.0

- name: Install Dependencies
run: pnpm install --no-frozen-lockfile
Expand Down
7 changes: 1 addition & 6 deletions .github/workflows/test.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ on:

jobs:
test:
if: contains(github.event.head_commit.message, 'release')
timeout-minutes: 10
runs-on: ${{ matrix.os }}
strategy:
Expand All @@ -46,8 +47,6 @@ jobs:

- name: Install pnpm
uses: pnpm/action-setup@v2
with:
version: 8.6.2

- name: Set node version to ${{ matrix.node_version }}
uses: actions/setup-node@v4
Expand Down Expand Up @@ -96,13 +95,9 @@ jobs:
name: 'Lint: node-LTS, ubuntu-latest'
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Install pnpm
uses: pnpm/action-setup@v2
with:
version: 8.6.2

- name: Set node version to LTS
uses: actions/setup-node@v3
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,5 @@ temp/*
.eslintcache
coverage
temp-spa
docs/.vitepress/dist
docs/.vitepress/cache
193 changes: 9 additions & 184 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,197 +1,22 @@

<p align="center">
<a href="https://vitejs.dev" style="margin-right: 32px;" target="_blank" rel="noopener noreferrer">
<img width="140" src="https://vitejs.dev/logo.svg" alt="Vite logo" />
</a>
<a href="https://www.typescriptlang.org/" target="_blank" rel="noopener noreferrer">
<img width="140" src="https://upload.wikimedia.org/wikipedia/commons/4/4c/Typescript_logo_2020.svg" alt="Typescript logo" />
</a>
<img width="180" src="./logo.svg" alt="Logo" />
</p>
<br/>
<p align="center">
<a href="https://npmjs.com/package/vite-plugin-public-typescript"><img src="https://img.shields.io/npm/v/vite-plugin-public-typescript.svg" alt="npm package"></a>
<a href="https://nodejs.org/en/about/previous-releases"><img src="https://img.shields.io/node/v/vite-plugin-public-typescript.svg" alt="node compatibility"></a>
</p>

# vite-plugin-public-typescript

**English** | [中文](./README.zh.md)

> A vite plugin inject typescript script into html
**Compile typescript files in the specified directory then inject them into html**

## Online Demo
[Demo](https://hemengke1997.github.io/vite-plugin-public-typescript/)

## Why

- If you want to execute some scripts before the page render
- If you don't want to inject `script` code into `index.html` in a hard-coded way
- If you want third-party scripts to have hash cache
- If you want your project to be all typescript
- ...

**`vite-plugin-public-typescript` is born to solve these problems elegantly**

## Install

```bash
pnpm add vite-plugin-public-typescript -D
```

## Scenes

- Independent third-party scripts, such as `sentry`, `google analytics`, `baidu statistics`, etc.
- Scripts that you want to execute before the page is fully loaded, such as [`lib-flexible`](https://github.com/amfe/lib-flexible), etc.
- Initialize global functions
- ...

## Features

- Output js files with `hash`, no need to worry about cache
- Default esbuild compilation, blazo fast!
- Support babel compilation, no need to worry about browser compatibility
- Support vite environment variables
- Support vite HMR
- Support different output modes (memory mode and file mode)
- Support CSR and SSR

## Options

| Option | Type | Default | Description |
| ---------------- | -------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `inputDir` | `string` | `public-typescript` | Directory of input typescript files |
| `publicDir` | `string` | publicDir of vite's config | Vite's publicDir |
| `outputDir` | `string` | '' | Directory of output javascript files after building |
| `esbuildOptions` | `BuildOptions` | `{}` | esbuild build options |
| `babel` | `boolean ｜ ESBuildPluginBabelOptions` | `false` | babel compilation (if you need to be compatible with browsers below es6, please turn it on) |
| `manifestName` | `string` | `manifest` | The name of the `manifest` file |
| `hash` | `boolean` | `true` | Whether the compiled `js` generates `hash` |
| `destination` | `string` | `memory` | Output mode: memory mode \| file mode |
| `cacheDir` | `string` | `node_modules/.vite-plugin-public-typescript` | The directory where the `manifest` cache is stored |
| `base` | `string` | vite config `base` | Resource base url |

## Usage

Note: The default value of 'inputDir' in 'publicTypescript' is 'public-typescript', you can also reconfigure this property.
Then you need to create a folder with the same name in the same directory as' vite.config.ts' and create a '.ts' file inside it

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { publicTypescript } from 'vite-plugin-public-typescript'

export default defineConfig({
plugins: [
// If you use the default configuration, the source code location 'inputDir' defaults to 'public-typescript'
publicTypescript(),
injectScripts((manifest) => [
{
attrs: {
// The file name in the directory, for example, test.ts --> manifest.test
src: manifest.someScript,
},
injectTo: 'head',
},
])
]
})
```
<h1 align="center">vite-plugin-public-typescript</h1>
<p align="center">Inject TypeScript into HTML</p>

### Typescript types

```json
{
"compilerOptions": {
"types": ["vite-plugin-public-typescript/virtual"]
}
}
```

### get manifest in client

Note: The code here can only be used in the project code, not in 'vite.config.ts' and other build time code, because it is generated after the build

```ts
import { manifest } from 'virtual:public-typescript-manifest'

console.log(manifest)
```

If you need to get the 'manifest' at build time, such as custom implementation of your own vite plugin 'injectScript', use the following code

```ts
import { getManifest } from 'vite-plugin-public-typescript';

console.log(getManifest())
```

### SPA

In `SPA` applications, we can inject scripts into `index.html` via the `injectScripts` plugin.

For a full example, see: [spa playground](./playground/spa/vite.config.ts)

#### vite config

```ts
import { defineConfig } from 'vite'
import { injectScripts, publicTypescript } from 'vite-plugin-public-typescript'

export default defineConfig({
plugins: [
publicTypescript(),
injectScripts((manifest) => [
{
attrs: {
src: manifest.spa,
},
injectTo: 'head-prepend',
}
])
],
})
```

### SSR


In an `SSR` application, we can easily change the html to be rendered by injecting a script into it, since the `html` is essentially just a string!

For a full example, see: [ssr playground](./playground/ssr/index.html)

#### vite config

```ts
import { defineConfig } from 'vite'
import { publicTypescript } from 'vite-plugin-public-typescript'
<br/>

export default defineConfig({
plugins: [
publicTypescript(),
],
})
```

#### server.js
[中文](./README.zh.md)

```ts
import { injectScriptsToHtml } from 'vite-plugin-public-typescript'
## Introduction

html = injectScriptsToHtml(html, (manifest) => [
{
attrs: {
src: manifest.ssr,
},
injectTo: 'head-prepend',
},
])
```
`vite-plugin-public-typescript` is a Vite plugin that injects TypeScript into HTML.

Read the [documentation](https://hemengke1997.github.io/vite-plugin-public-typescript/) to learn more.

## License

MIT

[npm-img]: https://img.shields.io/npm/v/vite-plugin-public-typescript.svg
[MIT](./LICENSE)
Loading

0 comments on commit a9e02e0

Please sign in to comment.