Security News
JSR Working Group Kicks Off with Ambitious Roadmap and Plans for Open Governance
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
@kentico/kontent-cli
Advanced tools
Command line interface tool that can be used for generating and running Kontent migration scripts
The Kontent CLI helps you when you need to change content models within your Kentico Kontent projects and migrate existing content to match the changes. The CLI provides you with guidance on how to write and run migration scripts.
NOTE: The Kontent CLI tool supports only Javascript files, so if you write your migrations in Typescript or any other language you have to transpile your code before running.
The Kontent CLI requires Node 10+ and npm 6+, and uses the Kontent Management SDK to manipulate content in your projects.
npm install -g @kentico/kontent-cli
The current version of the CLI is useful for creating and running migration templates. Let's go through creating your first migration for a Kentico Kontent project.
When you need to add new features to your project and app, it's better to verify the changes in a separate non-production environment. In Kentico Kontent, clone your project from the list of your projects.
To improve the learning curve of our new CLI, we've prepared a Kontent CLI boilerplate with examples on how to use the CLI. Clone the boilerplate GitHub repository on your drive. In the next step, you'll run a migration script from the boilerplate's Migrations
directory.
Open a command line and navigate to the root of the boilerplate folder (should be kontent-migrations-boilerplate
) and execute the following commands:
# Navigates to the root of the Kontent CLI boilerplate folder.
cd ./kontent-migrations-boilerplate
npm install
# Registers an environment (a pair of two keys, a project ID and API key used to manage the project) for migrations.
kontent environment add --name DEV --api-key <Api key> --project-id <Project ID> (Use the copy of your production project from the first step)
# Runs a specific migration.
npm run migrate 01_sample_init_createBlogType
Kontent CLI supports only running JavaScript migration files so in case you want to write in TypesSript, CoffeScript or in any other language you have to transpile your code before running. In the case of TypeScript, you may use this example from Kontent CLI boilerplate
That's it! You've run your first Kontent migration. This migration created a content type called Blog that contains three text elements named Title, Author and Text. The sample migration is written in TypeScript.
The boilerplate is configured to transpile TypeScript migrations into plain JavaScript so that the Kontent CLI can execute the migrations. Note that if you don't want to use TypeScript for your migrations, it's fine to write the migrations directly in JavaScript.
You should now be able to go through the other boilerplate sample migrations. The migration scripts in the Migrations directory all focus on one scenario – replacing a piece of text from the Author text element with Author content items, which contain more information about the author. This way you can replace the texts within your items by more complex objects containing, for example, images and rich text.
You can use similar approach for your own specific scenarios. For example, imagine you need to add display information to the images inserted in your articles. You may want to specify relative size or caption for each image. To do this, you would need to open each article and replace every image with a component that would contain the image and a few elements for image metadata. You'd create small migration scripts for separate parts of the scenario (such as creating a new type, updating the articles, and so on) and the migrations will take care of the process for all articles within your project.
Use the --help
parameter to display the help section for CLI tool.
kontent --help
Combine the --help
parameter with a specific command to learn more about that command.
kontent migration add --help
The supported commands are divided into groups according to their target, at this first version there are just to spaces "migration" and "environment" containing following commands:
environment add
– Store information about the environment locally.
.environments.json
.--project-id <your project ID> --api-key <management api key> --name <name of the environment>
.migration add --name <migration name>
– Generates a script file (in JavaScript or TypeScript) for running a migration on a Kentico Kontent project.
The file is stored in the Migrations
directory within the root of your repository.
Add your migration script in the body of the run
function using the Kontent Management SDK that was injected via the apiClient
parameter.
To choose between JavaScript and TypeScript when generating the script file, use the --template-type
option, such as --template-type "javascript"
.
The migration template contains an order
property that is used to run a batch of migrations (range or all) in the specified order. The order
must be a unique, positive integer or zero. There may be gaps between migrations, for example, the following sequence is perfectly fine 0,3,4,5,10
// Example migration template
import {MigrationModule} from "@kentico/kontent-cli";
const migration: MigrationModule = {
order: 1,
run: async (apiClient) => {
// TODO: Your migration code.
},
};
export default migration;
migration run
- Runs a migration script specified by file name (option --name <file name>
), or runs multiple migration scripts in the order specified in the migration files (options --all
or --range
).
--project <YOUR_PROJECT_ID> --api-key <YOUR_MANAGEMENT_API_KEY>
) or environment stored in the local configuration file (option --environment <YOUR_ENVIRONMENT_NAME>
).--force
parameter.--continue-on-error
) or whether you want to run in the debug mode (option --debug
) and get additional information for certain issues logged into the console.backup --action [backup|restore|clean]
- This command enables you to use Kontent backup manager
If you come across an error and you're not sure how to fix it, execute your migration script as follows and setup your debugger to the specified port.
node --inspect .\node_modules\@kentico\kontent-cli\lib\index.js migration run -n 07_sample_migration_publish -e DEV
Writing migration scripts can involve a lot of repetitive work, especially when it requires getting different object types and iterating through them. That's why we've decided to continue improving the developer experience and focus on that in upcoming releases. We plan to reduce the code that you need to write to the bare minimum by providing you with a "command builder". This builder will allow you to write migrations using queries and callbacks that should be applied to every object selected by that query. For example, select content types, all items based on the types, and all variants of the items, and execute your callback function on them.
The tool isn't reserved only for migrations. A valid use case could also be Kontent project data export and import, which could together with the possibility to clone/create/archive projects via the management API be a great way to e.g. run integration tests on the test environment that would be archived after the successful tests run.
Check out the contributing page to see the best places to file issues, start discussions, and begin contributing. We have lot of ideas on how to improve the CLI and developer experience with our product, but we'd love to hear from you so we can focus on your needs.
FAQs
Command line interface tool that can be used for generating and running Kontent migration scripts
The npm package @kentico/kontent-cli receives a total of 59 weekly downloads. As such, @kentico/kontent-cli popularity was classified as not popular.
We found that @kentico/kontent-cli demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 12 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.