Skip to content

Commit

Permalink
[misc] finish up docs-rewrite merge
Browse files Browse the repository at this point in the history
  • Loading branch information
ioj4 committed Aug 8, 2024
1 parent 72e102c commit 7d4a3d8
Show file tree
Hide file tree
Showing 5 changed files with 6 additions and 122 deletions.
5 changes: 3 additions & 2 deletions .github/workflows/docs-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@ name: Deploy documentation

on:
push:
branches: ["docs-rewrite"]

branches: [main]
paths:
- "packages/shelter-docs/**"
workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
Expand Down
4 changes: 1 addition & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,7 @@ However, you can still install it manually:

## How do I make a plugin?

See [the docs](packages/shelter-docs/README.md)

Also see [Lune's docs](https://github.com/uwu/shelter/tree/main/packages/lune#readme)
See [the docs](https://shelter.uwu.network/guides/)

## Is there a plugin repo / website / etc.?

Expand Down
110 changes: 1 addition & 109 deletions packages/lune/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,112 +2,4 @@

The build tool for shelter.

## Quick start

1. Clone the repo template (`npx degit uwu/shelter-template shelter-plugins` will do it)
2. `npm i` (or your package manager of choice)
3. Either edit the hello world plugin, or navigate to `plugins` and run `lune init` to make a new plugin
4. Run `lune ci` from the root of the plugin to build them!

Lune is intended to work hand-in-hand with the repo template - you absolutely can use it separately, it'll work fine,
but the repo template has Lune setup already,
[pnpm](https://pnpm.io/workspaces) and
[npm](https://docs.npmjs.com/cli/v7/using-npm/workspaces/) monorepos to start you off, and a suitable tsconfig.

## What is Lune?

Lune is an all-in-one tool for managing and building plugins for shelter.

It replaces a set of tools taped together with node and bash with a (fairly) robust and friendly command line tool.

It can create new plugins interactively, build plugins, and build monorepos.
In the future it will have a dev mode of sorts, but this is work in progress (watch this space!)

It currently is based on esbuild, which means builds are very fast, at the expense of ecosystem size and (maybe?)
output size.

## Getting up to speed with _monorepos_

A monorepo is a project structuring pattern in which you put all the components of your software in a single repository.
This applies to shelter plugins by using one repository to contain the source code for multiple plugins.

The shelter developers encourage use of monorepos for shelter plugin development,
and the template repo will give you a monorepo by default.

Lune supports monorepos natively via the `ci` command - instead of building each plugin separately in a script,
just put all of your plugins in `./plugins/plugin-1`, `./plugins/plugin-2`, etc., and Lune will build them all.

You can use a different subdirectory with `--repoSubDir <directory>`

All plugins in a monorepo share a single dependency lock file, and your installs should be faster.
To take advantage of this, you can use a supported package manager such as
[pnpm](https://pnpm.io/) (recommended), [yarn](https://yarnpkg.com/),
or [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces).

## Styling, Sass and CSS Modules

Lune supports [Sass](https://sass-lang.com/) and SCSS out of the box, and will compile them to CSS at build time.

Simply `import css from "./styles.css"`, `styles.sass`, `styles.scss`, and inject them with `shelter.ui.injectCss`.

Lune also optionally supports [CSS Modules](https://css-tricks.com/css-modules-part-1-need/).

To use CSS Modules, you simply need to set `cssModules` in the config file - see _Configuring Lune_.

Then, you need to change your import from `import css from "./mystyles.scss"` to `import classes from "./mystyles.scss"`.
This _is_ an unorthodox way of doing CSS Modules, and it means existing IDE support won't work
(due to this, this is under review), but other tools generally have another way to inject the css string!

The classes object contains the real classnames for you to use - an example speaks volumes!:

```css
/* no css modules */
.button {
margin: 1rem;
}
```

```js
// no css modules
import css from "./styles.css";
// make sure to call uninj() in your onUnload handler
const uninj = shelter.ui.injectCss(css);

export const MyComponent = () => <button class="button" />;
```

```css
/* with css modules */
.button {
margin: 1rem;
}
```

```js
// with css modules
import classes from "./styles.css";
// shelter injects and uninjects your css automatically

export const MyComponent = () => <button class={classes.button} />;
```

```css
/* css modules compiled css */
.button_8gljn_1 {
margin: 1rem;
}
```

## Configuring Lune

Lune can optionally be configured with a `lune.config.js` file. You typically want to place it in the root directory of your project.
All lune commands search for the `lune.config.js` in the following order: `--cfg <path>`, `pluginToBuild/lune.config.js`, the first config above `pluginToBuild/`

It is an ES module JS file which should `export default` an object containing the options. All options are optional.

The options are:

- `cssModules: boolean | "legacy"` - if CSS Modules are enabled, by default `false`
- `minify: boolean` - by default false, dev mode plugins are always unminified
- `prePlugins: Plugin[]` - [esbuild](https://esbuild.github.io/) plugins to run before Lune's transforms
- `postPlugins: Plugin[]` - esbuild plugins to run after Lune's transforms
Please refer to the [documentation](https://shelter.uwu.network/guides/lune) for more information.
3 changes: 0 additions & 3 deletions packages/shelter-docs/vercel.json

This file was deleted.

6 changes: 1 addition & 5 deletions packages/shelter-ui/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,4 @@

A set of UI components designed to look identical to Discord's, built entirely in solid.

Please look at the shelter documentation page (//TODO: hyperlink) for shelter UI.

Inside Discord, these are exported to you on `shelter.ui`.
Outside of Discord, use `@uwu/shelter-ui`, and import `@uwu/shelter-ui/compat.css` somewhere in your project to fix
missing styles.
Please refer to the [documentation](https://shelter.uwu.network/ui) for more information.

0 comments on commit 7d4a3d8

Please sign in to comment.