Skip to content

Commit c03c91c

Browse files
ganievsganievs
committed
feat: add README
Signed-off-by: Shamil Ganiev <[email protected]>
1 parent 6f7393c commit c03c91c

File tree

4 files changed

+344
-10
lines changed

4 files changed

+344
-10
lines changed

‎.changeset/breezy-wings-knock.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@platacard/backstage-plugin-scaffolder-backend-module-yaml-merge-actions': minor
3+
'@platacard/backstage-plugin-scaffolder-backend-module-json-merge-action': minor
4+
---
5+
6+
Add README

‎README.md‎

Lines changed: 65 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,71 @@
1-
# [Backstage](https://backstage.io)
1+
# Backstage Plugins Collection
22

3-
This is your newly scaffolded Backstage App, Good Luck!
3+
A collection of custom Backstage plugins developed by Platacard.
44

5-
To start the app, run:
5+
## Development
66

7-
```sh
7+
### Project Structure
8+
9+
```
10+
├── plugins/
11+
│ ├── scaffolder-backend-module-json-merge-action/
12+
│ └── scaffolder-backend-module-yaml-merge-actions/
13+
├── examples/
14+
│ └── template/
15+
├── scripts/
16+
├── package.json
17+
└── README.md
18+
```
19+
20+
## Contributing
21+
22+
1. Fork the repository
23+
2. Create a feature branch
24+
3. Make your changes
25+
4. Run tests and linting
26+
5. Submit a pull request
27+
28+
### Development Workflow
29+
30+
```bash
31+
# Install dependencies
832
yarn install
33+
34+
# Start development
935
yarn start
36+
37+
# Make changes and test
38+
yarn test
39+
40+
# Ensure code quality
41+
yarn lint
42+
yarn prettier:check
43+
```
44+
45+
## Versioning
46+
47+
This project uses [Changesets](https://github.com/changesets/changesets) for
48+
version management and publishing.
49+
50+
To create a changeset:
51+
52+
```bash
53+
yarn changeset
1054
```
55+
56+
## License
57+
58+
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for
59+
details.
60+
61+
## Support
62+
63+
For issues and questions:
64+
65+
- Open an issue in this repository
66+
- Check the [Backstage documentation](https://backstage.io/docs)
67+
- Review plugin-specific README files in the `plugins/` directory
68+
69+
---
70+
71+
Built with ❤️ for the Backstage community by Platacard.

‎plugins/scaffolder-backend-module-json-merge-action/README.md‎

Lines changed: 116 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,118 @@
1-
# @internal/backstage-plugin-scaffolder-backend-module-json-merge-action
1+
# backstage-plugin-scaffolder-backend-module-json-merge-action
22

3-
The json-merge-action backend module for the scaffolder plugin.
3+
A Backstage Scaffolder backend module that provides custom actions for merging
4+
JSON files during the scaffolding process.
45

5-
_This plugin was created through the Backstage CLI_
6+
## Overview
7+
8+
This plugin adds two powerful JSON merging actions to your Backstage Scaffolder:
9+
10+
- `json:merge-file` - Merges a single JSON file with inline data
11+
- `json:merge-files` - Merges multiple JSON files together
12+
13+
These actions are particularly useful when you need to combine configuration
14+
files, merge API responses, or consolidate JSON data during template execution.
15+
16+
## Installation
17+
18+
Add the plugin to your backend:
19+
20+
```bash
21+
# From your Backstage root directory
22+
yarn add --cwd packages/backend @platacard/backstage-plugin-scaffolder-backend-module-json-merge-action
23+
```
24+
25+
## Configuration
26+
27+
Add the module to your backend in `packages/backend/src/index.ts`:
28+
29+
```typescript
30+
import { createBackend } from "@backstage/backend-defaults";
31+
32+
const backend = createBackend();
33+
34+
// ... other modules
35+
36+
backend.add(
37+
import(
38+
"@platacard/backstage-plugin-scaffolder-backend-module-json-merge-action"
39+
),
40+
);
41+
42+
backend.start();
43+
```
44+
45+
## Actions
46+
47+
### json:merge-file
48+
49+
Merges a JSON file with inline data using the
50+
[json-merger](https://www.npmjs.com/package/json-merger) library.
51+
52+
#### Input Schema
53+
54+
| Parameter | Type | Required | Description |
55+
| ------------------ | ------ | -------- | ------------------------------------------------------------------------ |
56+
| `inputFile` | string | Yes | The file in the working directory to merge |
57+
| `outputFileName` | string | Yes | The name of the file to write to |
58+
| `outputFilePath` | string | No | The path to output the file to. Defaults to the task's working directory |
59+
| `jsonMergeOptions` | object | No | Options to pass to the JSON merge function |
60+
61+
#### Example Usage
62+
63+
```yaml
64+
apiVersion: scaffolder.backstage.io/v1beta3
65+
kind: Template
66+
metadata:
67+
name: json-merge-example
68+
title: JSON Merge Example
69+
spec:
70+
steps:
71+
- id: merge-config
72+
name: Merge Configuration
73+
action: json:merge-file
74+
input:
75+
inputFile: base-config.json
76+
outputFileName: merged-config.json
77+
outputFilePath: config
78+
```
79+
80+
### json:merge-files
81+
82+
Merges multiple JSON files together into a single output file.
83+
84+
#### Input Schema
85+
86+
| Parameter | Type | Required | Description |
87+
| ------------------ | -------- | -------- | ------------------------------------------------------------------------ |
88+
| `inputFiles` | string[] | Yes | Array of files in the working directory to merge |
89+
| `outputFileName` | string | Yes | The name of the file to write to |
90+
| `outputFilePath` | string | No | The path to output the file to. Defaults to the task's working directory |
91+
| `jsonMergeOptions` | object | No | Options to pass to the JSON merge function |
92+
93+
#### Example Usage
94+
95+
```yaml
96+
apiVersion: scaffolder.backstage.io/v1beta3
97+
kind: Template
98+
metadata:
99+
name: multi-json-merge-example
100+
title: Multiple JSON Merge Example
101+
spec:
102+
steps:
103+
- id: merge-configs
104+
name: Merge Multiple Configurations
105+
action: json:merge-files
106+
input:
107+
inputFiles:
108+
- defaults.json
109+
- environment.json
110+
- overrides.json
111+
outputFileName: final-config.json
112+
outputFilePath: dist
113+
```
114+
115+
## JSON Merge Options
116+
117+
The `jsonMergeOptions` parameter accepts configuration options from the
118+
[json-merger](https://www.npmjs.com/package/json-merger) library.

‎plugins/scaffolder-backend-module-yaml-merge-actions/README.md‎

Lines changed: 157 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,159 @@
1-
# @internal/backstage-plugin-scaffolder-backend-module-yaml-merge-actions
1+
# backstage-plugin-scaffolder-backend-module-yaml-merge-actions
22

3-
The yaml-merge-actions backend module for the scaffolder plugin.
3+
A Backstage Scaffolder backend module that provides a custom action for merging
4+
YAML files with configurable merge strategies.
45

5-
_This plugin was created through the Backstage CLI_
6+
## Overview
7+
8+
This plugin adds a `yaml:merge` action to your Backstage Scaffolder that allows
9+
you to merge YAML files during the scaffolding process. It supports different
10+
merge strategies for arrays and preserves YAML structure and comments.
11+
12+
## Features
13+
14+
- **Deep merging** of YAML structures
15+
- **Configurable array merge strategies**: concat, replace, or unique
16+
- **Comment preservation** in YAML files
17+
- **Dry run support** for testing
18+
- **Flexible output paths** for generated files
19+
20+
## Installation
21+
22+
Add the plugin to your backend:
23+
24+
```bash
25+
# From your Backstage root directory
26+
yarn add --cwd packages/backend @platacard/backstage-plugin-scaffolder-backend-module-yaml-merge-actions
27+
```
28+
29+
## Configuration
30+
31+
Add the module to your backend in `packages/backend/src/index.ts`:
32+
33+
```typescript
34+
import { createBackend } from "@backstage/backend-defaults";
35+
36+
const backend = createBackend();
37+
38+
// ... other modules
39+
40+
backend.add(
41+
import(
42+
"@platacard/backstage-plugin-scaffolder-backend-module-yaml-merge-actions"
43+
),
44+
);
45+
46+
backend.start();
47+
```
48+
49+
## Action: yaml:merge
50+
51+
Merges two YAML files with customizable merge strategies.
52+
53+
### Input Schema
54+
55+
| Parameter | Type | Required | Description |
56+
| ------------------ | ------ | -------- | ------------------------------------------------------------------------ |
57+
| `inputFile` | string | Yes | The file in the working directory to merge |
58+
| `overlayFile` | string | Yes | The file containing data to merge into the input file |
59+
| `outputFileName` | string | Yes | The name of the file to write to |
60+
| `outputFilePath` | string | No | The path to output the file to. Defaults to the task's working directory |
61+
| `yamlMergeOptions` | object | No | Options to control how YAML files are merged |
62+
63+
#### yamlMergeOptions
64+
65+
| Option | Type | Default | Description |
66+
| -------------------- | ------- | -------- | -------------------------------------------------------------------- |
67+
| `arrayMergeStrategy` | string | `concat` | How to merge arrays: `concat`, `replace`, or `unique` |
68+
| `prependOnConcat` | boolean | `false` | When using concat strategy, prepend overlay arrays instead of append |
69+
70+
### Output Schema
71+
72+
| Parameter | Type | Description |
73+
| ------------ | ------ | ------------------------------------------------------ |
74+
| `outputFile` | string | Path to the merged output file (relative to workspace) |
75+
76+
### Example Usage
77+
78+
```yaml
79+
apiVersion: scaffolder.backstage.io/v1beta3
80+
kind: Template
81+
metadata:
82+
name: yaml-merge-example
83+
title: YAML Merge Example
84+
spec:
85+
steps:
86+
- id: merge-kubernetes-configs
87+
name: Merge Kubernetes Configurations
88+
action: yaml:merge
89+
input:
90+
inputFile: base-deployment.yaml
91+
overlayFile: production-overrides.yaml
92+
outputFileName: final-deployment.yaml
93+
outputFilePath: k8s
94+
yamlMergeOptions:
95+
arrayMergeStrategy: unique
96+
```
97+
98+
## Merge Strategies
99+
100+
### Object Merging
101+
102+
Objects are deeply merged. Keys from the overlay file override or add to the
103+
input file.
104+
105+
```yaml
106+
# Input file
107+
config:
108+
database:
109+
host: localhost
110+
port: 5432
111+
112+
# Overlay file
113+
config:
114+
database:
115+
port: 5433
116+
cache:
117+
enabled: true
118+
119+
# Result
120+
config:
121+
database:
122+
host: localhost
123+
port: 5433
124+
cache:
125+
enabled: true
126+
```
127+
128+
### Array Merge Strategies
129+
130+
#### concat (default)
131+
132+
Concatenates arrays from both files.
133+
134+
```yaml
135+
# Input: [a, b]
136+
# Overlay: [c, d]
137+
# Result: [a, b, c, d]
138+
# With prependOnConcat: [c, d, a, b]
139+
```
140+
141+
#### replace
142+
143+
Replaces the entire array with the overlay array.
144+
145+
```yaml
146+
# Input: [a, b]
147+
# Overlay: [c, d]
148+
# Result: [c, d]
149+
```
150+
151+
#### unique
152+
153+
Merges arrays keeping only unique values.
154+
155+
```yaml
156+
# Input: [a, b, c]
157+
# Overlay: [b, c, d]
158+
# Result: [a, b, c, d]
159+
```

0 commit comments

Comments
 (0)