npm package: @peachy/plugin-resources
Description: Import resources in your app
Latest version: 0.0.14

# @peachy/plugin-resources

Allow you to import files as resources.

> NOTE: In dev mode, your resources will NOT be watched for changes and live-reloaded.

## Usage

You will need to have `peachy` installed.

### Configuration

Then you will need to create a peachy configuration file. There are two ways to do this:

#### 1. Use `peachy.config.ts`

You can create a `peachy.config.ts` file in the root of your project.

```ts
// peachy.config.ts

import { defineConfig } from "@peachy/core";

export default defineConfig({
  applicationId: "dev.peachy.Example",
  resources: {
    icons: true,
  },
});
```

#### 2. Use a field in `package.json`

You can also add a special `peachy` field in your existing package.json

```json
// package.json
{
  "peachy": {
    "applicationId": "dev.peachy.Example",
    "resources": {
      "icons": true
    }
  }
}
```

### Initialization

In your code, make sure to initialize your code to use the given name in your `peachy.config.ts` file.

```tsx
import Gtk from "gi://Gtk?version=4.0";

const app = new Gtk.Application({
  // IMPORTANT: match this with the one in the configuration file
  application_id: "dev.peachy.Example",
  flags: Gtk.ApplicationFlags.FLAGS_NONE,
});

/// ...

app.run([]);
```

Then you can start importing resources/icons.

### Importing Files

When you need to import a resource, you can directly import them. Currently, only SVG files are supported.

```tsx
import Gtk from "gi://Gtk?version=4.0";

import File from "./path/to/file.svg";

const image = new Gtk.Image({
  resource: File,
});
```

You can use the imported resource anywhere that accepts a `Gio.Resource` like `Gtk.Image` and `Gtk.Picture`.

### Icons

Icons in `data/icons` folder will be automatically configured and registered as Themed Icons, so you can use them just by referencing their name.

If your icons are in a different folder, you can specify the path in the configuration file.

```ts
// peachy.config.ts

import { defineConfig } from "@peachy/core";

export default defineConfig({
  applicationId: "dev.peachy.Example",
  resources: {
    // specify the path to your icons folder
    icons: "./path/to/icons",
  },
});
```

#### 1. Put your icons in `data/icons` folder.

```
data/icons/right-symbolic.svg
data/icons/left-symbolic.svg
```

#### 2. Use them in your code.

```tsx
import Gtk from "gi://Gtk?version=4.0";

const button = new Gtk.Button({
  icon_name: "right-symbolic",
});
```

### Bundle resources

If you have resources that you want to always be bundled in your application, you can "bundle" them.

These files can be read by objects that uses "Automatic resources" such as
[Gtk.Application](https://gnome.pages.gitlab.gnome.org/gtk/gtk4/class.Application.html#automatic-resources) and
[Adw.Application](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Application.html).

A few use cases are given below:

- The `gtk/help-overlay.ui` file will be used to display application help.
- The `style.css` file will be automatically loaded and applied to your application.

```ts
// peachy.config.ts

import { defineConfig } from "@peachy/core";

export default defineConfig({
  applicationId: "dev.peachy.Example",
  resources: {
    bundle: [
      // this assumes that the file is located at `gtk/help-overlay.ui`
      "gtk/help-overlay.ui",
      // if you have a file located elsewhere, you can specify the path and alias it will be available at
      { path: "./path/to/style.css", alias: "style.css" },
    ],
  },
});
```