Skip to main content
Version: v4.4.0

Create a Versioned Stack

Before you begin

This tutorial creates a Stack with Template/Plugin and version the entire Stack initializing Git with your remote repository.

Background

The example in this tutorial creates a Stack and a Template with some Javascript code. The idea is to create a Plugin that removes the Javascript file (index.js) and generates another file with Typescript code, the index.ts.

After applying the Plugin, the final code will have a file:

  • package.json
  • index.ts
  • tsconfig.json The Plugin transforms javascript into Typescript.

Prerequisites

  • Your Git repository must be public to import Stack into your environment.
  • Create a folder named "app" to run the tests.

Follow the steps below:

Step 1. Create your Stack

Add the parameter --remote to the command to create the Stack:

stk create stack --remote <url-repository>

If you do not give your Stack a name, your repository's name will be the one. This happens after you commit to version it in the next step.

Stack was created with the default structure:

│ .gitignore
stack.png
│ stack.yaml

├───docs
│ about.md
│ use-case.md

└────stackfiles
default.yaml

Step 2. Versioning your Stack

Run in terminal:

git push

If there are any errors in your branch, use the command:

git push --set-upstream origin main

Your stack has been versioned!

info

You can also import this Stack into your local environment by running the command:

 stk import stack <url-repository>

The terminal should return:

Downloading stack from url <url-repository>... 
- Stack downloaded successfully!
- Verifying stack content...
- Stack is valid!
- Stack added and ready for use!

Step 3. Create the Template**

Execute the command below in your terminal:

stk create template <template-name>

The template is created in the default structure:

name-of-their-template
│ template.yaml

└───templates
README.md

Step 4. Versioning your Template

Version your Template in the Stack. Execute the commands:

git add .
git commit

And then:

git push

Step 5. Create file and edit Template

In the Stack folder, click on your Template folder and inside it create a file named `index.js`` and copy and paste the content below:

helloStackSpot('{{project_name}}')

function helloStackSpot(projectName) {
console.log(``Project ${projectName} created with StackSpot!`)
console.log('See more on creating templates at: https://docs.stackspot.com/v3.7.0creators-guide/guides/howto-create-template/')
}
  • Edit the templates/template.yaml file and add the input project_name: global: true

See the example below:

inputs:
- label: project name
type: text
name: project_name
default: project-name
global: true # Attribute added to tell which input can be used in the applied plugins

Step 6. Versioning the change

Now run the commands to version the Template change in your Stack:

git add .
git commit

And then:

git push

Step 7. Create an Application and Test the Template

After editing the file, execute the command below outside your Stack's folder:

stk create app-name-your-app --template-path <template_local-directory-path>

The output in the terminal should be:

- Application app-name-of-app successfully created!
info

After versioning your Stack and the Template push done, you can update the Stack in your environment:

stk update stack stack-name

You can also create an app and test the Template, run the command below:

 stk create app name-of-your-app --template <stack-name/template-name>

The terminal returns:

- Application name-of-your-app successfully created!

Now your template has been used to create an application! To test this, go to the directory you created and execute the command node index.js

The terminal returns:

Name-of-your-app project created with StackSpot!
Learn more about creating templates at: https://docs.stackspot.com/v3.7.0creators-guide/guides/howto-create-template/

Step 8. Create the Plugin

In your Stack folder, run the command to create your Plugin:

stk create plugin <typescript-plugin>

typescript-plugin is the name of the Plugin in this example, you can use another one.

The Plugin has the default structure:

typescript-plugin
plugin.png
plugin.yaml

├───docs
│ about.md
│ implementation.md
│ usage.md
│ use-case.md

└───templates
README.md

Step 9. Apply the Plugin

Enter the app folder, then enter the application folder you created in Step 7 and execute the command:

stk apply plugin --plugin-path <plugin-path>

Step 10. Version the change

To version change of the Plugin in your Stack, run:

git add .
git commit

And then:

git push

Step 11. Edit the Plugin

Go to the Plugin folder you have created, click on the folder templates and you need to create 3 files in this folder, see:

1. Create a file named index.ts and copy and paste the content below:

const projectName: string = '{{project_name}}'
helloStackSpot(projectName)

function helloStackSpot(projectName: string) {
console.log(`Project ${projectName} created with StackSpot!`)
console.log('See more on creating templates at: https://docs.stackspot.com/v3.7.0creators-guide/guides/howto-create-template/')
console.log('More on creating plugins at: https://docs.stackspot.com/v3.7.0creators-guide/guides/howto-create-plugin/')
}

2. Create other package.json file and add the content below:

{
"name": "{{project_name}}",
"version": "1.0.0",
"description": "{{project_description}}",
"main": "index.js",
"scripts": {
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"devDependencies": {
"@types/jest": "^28.1.6",
"@types/node": "^18.6.4",
"jest": "^28.1.3",
"ts-jest": "^28.0.7",
"ts-node": "^10.9.1",
"typescript": "^4.7.4"
}
}

4. Create another file in the directory named tsconfig.json and add the content:

{
"compilerOptions": {
"alwaysStrict": true,
"charset": "utf8",
"declaration": true,
"experimentalDecorators": true,
"incremental": true,
"inlineSourceMap": true,
"inlineSources": true,
"lib": [
"es2019",
"dom"
],
"module": "CommonJS",
"newLine": "lf",
"noEmitOnError": true,
"noFallthroughCasesInSwitch": true,
"noImplicitAny": true,
"noImplicitReturns": true,
"noImplicitThis": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"resolveJsonModule": true,
"strict": true,
"strictNullChecks": true,
"strictPropertyInitialization": true,
"stripInternal": false,
"target": "ES2019",
"composite": false,
"tsBuildInfoFile": "tsconfig.tsbuildinfo"
},
"include": [
"**/*.ts"
],
"exclude": [
"node_modules",
"test/**/expected-src",
"generated-src",
"build/**/*"
],
}

You need to change some details for your Plugin work, see below:

# inputs:
# - label: Input Example
# type: text
# name: example
# default: any text
# - label: Example of number
# type: int
# name: any_number
# default: "10"
# - label: Example of list
# type: multiselect
# name: any_list
# items:
# - item1
# - item2

1. Remove the inputs you didn't use, keep only the input below, copy the content

inputs:
- label: Enter the project description
type: text
name: project_description
default: Project Created with StackSpot
info

The values inside the double braces {{input_value }} will be interpolated with the values you entered in the inputs during the Plugin application.

2. Add the Declarative Hooks of run type in the plugin.yaml file:

hooks:
- type: run
trigger: before-render
mac:
- rm index.js
linux:
- rm index.js
windows:
- del index.js
- type: run
trigger: after-render
commands:
- echo "Installing dependencies..."
- type: run
trigger: after-render
mac:
- npm install
- npm run build
linux:
- npm install
- npm run build
windows:
- npm.cmd install
- npm.cmd run build
- type: run
trigger: after-render
commands:
- echo "Test the plugin by running `node index`"
info

Hooks are added to:

  • Remove index.js file before creating index.ts file by Plugin (no longer used);
  • Install dependencies;
  • Run build of the project.

For more information, check out the Declarative Hooks page.

At the end, a message is displayed and tells you how to test after applying the Plugin.

Step 13. Versioning the change**

To version the Plugin change in your Stack, execute:

git add .
git commit

And then:

git push

Step 14. Testing the Plugin

Enter the app folder, then enter the application folder you created in step 7 and run the command below:

stk apply plugin --plugin-path <plugin-local-path>

The terminal returns:

Test the plugin by running `node index`.
- typescript-plugin applied.

After versioning the Stack and pushing the Plugin, update the Stack in your environment by running:

stk update stack name-stack

Now, test the Plugin with the command below:

stk apply plugin <stack-name>/<typescript-plugin>

The terminal returns:

Test the plugin by running `node index`.
- typescript-plugin applied.

There you go, your Plugin has been used in an application!

  • To test, execute the command node index and the terminal returns:
Test-template project created with StackSpot!
Read more about how to create templates at: https://docs.stackspot.com/v3.7.0creators-guide/guides/howto-create-template/
Read more about how to create plugins at: https://docs.stackspot.com/v3.7.0creators-guide/guides/howto-create-plugin/

Was this page helpful?