Skip to main content
Version: v4.5.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-legacy 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-legacy 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-legacy 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.legacy.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-legacy 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-legacy update stack stack-name

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

 stk-legacy 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.legacy.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-legacy 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-legacy 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.legacy.stackspot.com/v3.7.0creators-guide/guides/howto-create-template/')
  console.log('More on creating plugins at: https://docs.legacy.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-legacy 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-legacy update stack name-stack

Now, test the Plugin with the command below:

stk-legacy 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.legacy.stackspot.com/v3.7.0creators-guide/guides/howto-create-template/
Read more about how to create plugins at: https://docs.legacy.stackspot.com/v3.7.0creators-guide/guides/howto-create-plugin/

Was this page helpful?