Skip to content

Commit

Permalink
docs: initial setup
Browse files Browse the repository at this point in the history
  • Loading branch information
@johannschopplich
johannschopplich committed Feb 3, 2024
1 parent c98b62d commit dc9ee2e
Show file tree
Hide file tree
Showing 27 changed files with 1,693 additions and 333 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
node_modules
dist
**/.vitepress/cache
.cache
.DS_Store
.local
255 changes: 33 additions & 222 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,53 +1,43 @@
# kirbyup
[![kirbyup](./docs/public/og.jpg)](https://kirbyup.byjohann.dev)

> [!TIP]
> Take a look into Kirby's [pluginkit](https://github.com/getkirby/pluginkit/tree/4-panel) repository for an example setup.
# kirbyup

The fastest and leanest way to bundle your Kirby Panel plugins. No configuration necessary.
[![npm version](https://img.shields.io/npm/v/kirbyup?color=a1b858&label=)](https://www.npmjs.com/package/kirbyup)

## Key Features
The official bundler for Kirby Panel plugins with zero-config usage and built-in HMR.

- 🍂 Lightweight, robust and tested
- ⚡️ Fast compilation with Vite/esbuild
- 🔄 Hot module replacement and watch mode
- \*️⃣ `kirbyup.import` to [auto-import blocks & fields](#auto-import-blocks-and-fields)
- 🎒 [PostCSS support](#postcss)
- 🧭 [Path resolve aliases](#path-resolve-aliases)
- 🔌 [Env variables support](#env-variables)
- 🦔 [Extendable configuration with `kirbyup.config.js`](#extendable-configuration-with-kirbyupconfigjs)
- [✨  Release Notes](https://github.com/johannschopplich/kirbyup/releases)
- [📖  Read the documentation](https://kirbyup.byjohann.dev)

## Get Started Right Away

… With one of the following Panel plugin kits:
## Key Features

- [`eslint`](./examples/eslint)
- [`tailwindcss`](./examples/tailwindcss)
- 🔄 [Hot module replacement](https://kirbyup.byjohann.dev/guide/getting-started.html#development)
- 🎒 PostCSS support
- 🧭 Add custom path aliases
- 🔌 Run actions based on environment variables
- 🦔 [Extends Vite with `kirbyup.config.js`](https://kirbyup.byjohann.dev/guide/config-file)

I highly recommend using one of these starters instead of [Kirby's default `pluginkit`](https://github.com/getkirby/pluginkit/tree/4-panel). They provide a better developer experience out of the box.
## Setup

## Installation
> [!TIP]
> [📖 Read the documentation](https://kirbyup.byjohann.dev)
If you want to use kirbyup right away, there is no need to install it. Simply call it with `npx`:
```bash
# pnpm
pnpm add -D kirbyup

```json
{
"scripts": {
"dev": "npx -y kirbyup serve src/index.js",
"build": "npx -y kirbyup src/index.js"
}
}
# npm
npm i -D kirbyup
```

> [!NOTE]
> If `npx` doesn't use the latest kirbyup version, although it is available, run `npx -y kirbyup@latest` instead or delete the `~/.npm/_npx` cache folder.
## Basic Usage

While kirbyup will stay backwards compatible, exact build reproducibility may be of importance to you. If so, I recommend targeting a specific package version, rather than using `npx`. Install kirbyup with a package manager of your choice locally to your project:

```bash
npm i kirbyup --save-dev
```
> [!TIP]
> [📖 Read the documentation](https://kirbyup.byjohann.dev) or skip starting from scratch and pick one of the following starters:
> - [`eslint`](./examples/eslint)
> - [`tailwindcss`](./examples/tailwindcss)
Example package configuration:
Having installed kirbyup, you can add the following scripts as shortcuts to the commands you will use most often:

```json
{
Expand All @@ -56,197 +46,18 @@ Example package configuration:
"build": "kirbyup src/index.js"
},
"devDependencies": {
"kirbyup": "latest"
"kirbyup": "^3.1.3"
}
}
```

Global installation is supported as well, but not recommended.

## Usage

### Development

Start a development server for the Panel plugin:

```bash
kirbyup serve src/index.js
```

This creates `./index.dev.mjs`, telling Kirby to load the development version of the plugin from the dev server started by `kirbyup serve`, enhanced by features like hot module replacement and auto-reload.

If you prefer the watch mode to build a development bundle of the final Panel plugin or develop in an older version of Kirby (prior to 3.7.4), run:

```bash
kirbyup src/index.js --watch
```

### Production

```bash
kirbyup src/index.js
```

The final panel plugin will be bundled, minified, and written into the current directory as `./index.js` and `./index.css`.

## Built-in Features

### PostCSS

If the project contains a valid PostCSS config (any format supported by [postcss-load-config](https://github.com/postcss/postcss-load-config), e.g. `postcss.config.js`), it will be automatically applied to all imported CSS.

If no configuration file is found, kirbyup will apply two PostCSS plugins which the Kirby Panel uses as well to let you embrace the same functionality within your Panel plugins. The following PostCSS transforms are applied by kirbyup:

- [postcss-logical](https://github.com/csstools/postcss-logical) lets you use logical, rather than physical, direction and dimension mappings in CSS, following the [CSS Logical Properties and Values](https://drafts.csswg.org/css-logical/) specification.
- [postcss-dir-pseudo-class](https://github.com/csstools/postcss-dir-pseudo-class) lets you style by directionality using the `:dir()` pseudo-class in CSS, following the [Selectors](https://www.w3.org/TR/selectors-4/#the-dir-pseudo) specification. It gives you the same syntax Kirby uses for full compatibility with RTL localizations of the Panel.

### Path Resolve Aliases

Import certain modules more easily by using the `~/` path alias. It will resolve to the directory of your input file, for example `src` when building `kirbyup src/index.js`.

Now, given a deeply nested component, instead of using relative paths when importing like so:

```js
// Inside deeply nested module
import someUtility from '../../utils'
```

You can use the alias:

```js
import someUtility from '~/utils'
```

> [!TIP]
> You can use `@/` as path alias as well.
### Auto-Import Blocks and Fields

If you find yourself in the situation of needing to import multiple **blocks** or **fields** into your Panel plugin, you can use the kirbyup `kirbyup.import` function to ease the process.

Before:

```js
import Foo from './components/blocks/Foo.vue'
import Bar from './components/blocks/Bar.vue'
import Maps from './components/blocks/Maps.vue'

window.panel.plugin('kirbyup/example', {
blocks: {
foo: Foo,
bar: Bar,
maps: Maps
}
})
```

After:

```js
import { kirbyup } from 'kirbyup/plugin'

window.panel.plugin('kirbyup/example', {
blocks: kirbyup.import('./components/blocks/*.vue')
})
```

### Env Variables

kirbyup exposes env variables on the special `import.meta.env` object. Some built-in variables are available in all cases:

- **`import.meta.env.MODE`** (`development` | `production`): the mode kirbyup is running in.
- **`import.meta.env.PROD`** (`boolean`): whether kirbyup is running in production.
- **`import.meta.env.DEV`** (`boolean`): whether kirbyup is running in development (always the opposite of `import.meta.env.PROD`)

During production, these env variables are **statically replaced**. It is therefore necessary to always reference them using the full static string. For example, dynamic key access like `import.meta.env[key]` will not work.

#### `.env` Files

kirbyup (thanks to Vite) uses [dotenv](https://github.com/motdotla/dotenv) to load additional environment variables from the `.env` and `.env.local` files in your plugin's root directory.

Loaded env variables are also exposed to your source code via `import.meta.env`.

To prevent accidentally leaking env variables for distribution, only variables prefixed with `KIRBYUP_` or `VITE_` are exposed to your processed code. Take the following file as an example:

```ini
DB_PASSWORD=foobar
KIRBYUP_SOME_KEY=123
```

Only `KIRBYUP_SOME_KEY` will be exposed as `import.meta.env.VITE_SOME_KEY` to your plugin's source code, but `DB_PASSWORD` will not.

### Extendable Configuration With `kirbyup.config.js`

Create a `kirbyup.config.js` or `kirbyup.config.ts` configuration file the root-level of your project to customize kirbyup.

```js
import { fileURLToPath } from 'node:url'
import { resolve } from 'node:path'
import { defineConfig } from 'kirbyup/config'

const currentDir = fileURLToPath(new URL('.', import.meta.url))

export default defineConfig({
alias: {
'#plugin/': `${resolve(currentDir, 'src/plugin')}/`
},
vite: {
define: {
__PLAYGROUND__: JSON.stringify(process.env.PLAYGROUND)
}
}
})
```
#### `alias`
When aliasing to file system paths, always use absolute paths. Relative alias values will be used as-is and will not be resolved into file system paths.
#### `vite`
You can build upon the defaults kirbup uses and extend the Vite configuration with custom plugins etc.
For a complete list of options, take a look at the [Vite configuration options](https://vitejs.dev/config/).
## Options
> [!TIP]
> Inspect all available options with `kirbyup --help` and `kirbyup serve --help`.
### `kirbyup <input>`
##### `--out-dir <dir>`
The output directory to save the processed code into. Defaults to the current working directory.
##### `--watch [path]`
Enables watch mode. If no path is specified, kirbyup watches the folder of the input file. Repeat `--watch` for multiple paths.
### `kirbyup serve <input>`
##### `--port <port>`
The port for the development server to run on. Defaults to `5177`.
##### `--out-dir <dir>`
The output directory where the plugin file read by Kirby is saved. Defaults to the project root.
##### `--watch <path>`
Specifies additional files that should be watched for changes, with changes causing the page to reload. Repeat `--watch` for multiple paths.
> [!NOTE]
> By default, kirbyup will watch all PHP files (`./**/*.php`) in the plugin directory and reload the page if it detects changes. Using `--watch` to set your own path overrides this setting, so you need to add the PHP glob explicitly if you want to keep the behavior: `--watch ./my/files/* --watch ./**/*.php`
##### `--no-watch`
Disables the default behavior of watching all PHP files for changes.
## Credits
## 💻 Development

- [Vite](https://vitejs.dev) by Evan You and all of its contributors.
1. Clone this repository
2. Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
3. Install dependencies using `pnpm install`
4. Run `pnpm run dev:prepare`
5. Start development server using `pnpm run dev`

## License

Expand Down
Loading

0 comments on commit dc9ee2e

Please sign in to comment.