Repository files navigation

Read theofficial documentation.

LockBlocks is a Node.js command line utility that allows you to easily update projects created from a starter.

Starters are an excellent way to hit the ground running with any new project without needing to write a bunch of boilerplate code. Simply clone the starter and build.

However, the moment you create a new project from a starter, you create a new maintenance fork. If you update the starter, any projects created from that starter will also need to be updated, and usually this must be done manually.

This can quickly snowball into a lot of work if you are maintaining several projects created from the same starter. Bugs can easily be introduced when manually updating projects, or you may simply forget to copy updates to each project.

Enter LockBlocks. With LockBlocks, you can configure an updater that specifies which files and directories should be updated from the starter.

You can specify fields to update in JSON and YAML files, such as your dependencies inpackage.json, with granular control over how the updates are made for each field (merge, fill, replace, etc).

In addition, you can specify blocks of code that will be pulled from the starter when updating. This gives you a lot of control over what can be maintained in the starter, as you can lock parts of a file that are maintained in the starter, while leaving the rest of the file to be changed as the developer sees fit.

• 🔄Create the updater your starter project is missing.
  • Make maintenance of child projects easier with a custom updater.
• 🟥Lock blocks of code.
  • Use lock tags around blocks of code to synchronize those blocks with your starter.
• 🗂️Rename, replace, fill, delete, and more.
  • Flexible and customizable file and directory update options.
• 📄Fine-grained config file updates.
  • Updatepackage.json scripts and dependencies, or any other JSON or YAML files, as you see fit!
• 🪵Verbose logging.
  • Know exactly what changed and what was updated.

If this project helped save you time, please consider buying me a coffee, which powers my development (and life). Your support is much appreciated!

• Documentation
• Overview
  • The Problem
  • The Solution
  • Features include:
• Donate
• Table of Contents
• Installation
• Quick Start
  • Git Approach
• Usage
• How It Works
  • Order of Operations
• TypeScript
• Icon Attribution
• Contributing
• ⭐ Found It Helpful? Star It!
• License

npm i --save-dev lockblocks

Create a new file at the root of your starter project calledlockblocks.yml:

# lockblocks.ymlrenameFiles:[]replaceFiles:  -lockblocks.ymlfillFiles:[]deleteFiles:[]excludePaths:  -.git  -.lockblocks  -node_modulesupdateJson:   -path:package.jsonroot:fill:trueupdateFields:      -key:versionas:starterVersion      -key:scriptsmerge:true      -key:dependenciesmerge:true      -key:devDependenciesmerge:trueupdateYaml:[]

This config will keep yourlockblocks.yml and npm scripts and packages up to date, and will copy the starter'sversion inpackage.json asstarterVersion.

Then create an npm script inpackage.json to execute LockBlocks using a git project as the origin and the current project as the target. See below.

To update your project with LockBlocks using a git project as the origin, add this script topackage.json:

"scripts": {"update":"git clone -q git@github.com:my-username/my-starter.git ./.lockblocks && lockblocks ./.lockblocks . --verbose && rm -rf .lockblocks"},

...wheregit@github.com:my-username/my-starter.git is the location to your starter git project.

This script will silently clone your project to the.lockblocks directory, then run LockBlocks using that dir as the origin and the current directory as the target. The.lockblocks directory will then be deleted when finished.

With this approach, be sure.lockblocks is specified inexcludePaths.

See theUsage Documentation for full usage docs.

This utility uses a config file,lockblocks.yml, to determine which files and directories to update in your project.

It also scans all files in the starter (origin directory) for special tags that specify additional updates to make, including blocks of code.

You can reference the order in which LockBlocks performs updates below.

LockBlocks operates in the following order:

1. Rename files - Files are renamed as perrenameFiles and thelock-rename tags found in origin.
2. Replace files - Files are replaced as perreplaceFiles and thelock-all tags found in origin.
3. Fill files - Missing files are filled in as perfillFiles.
4. Delete files - Files are deleted as perdeleteFiles.
5. Replace code blocks - Code blocks are updated as per thelock block tags found in origin.
6. Update JSON - All JSON files will be updated as perupdateJson.
7. Update YAML - All YAML files will be updated as perupdateYaml.

Type definitions have been included forTypeScript support.

Favicon byTwemoji.

Open source software is awesome and so are you. 😎

Feel free to submit a pull request for bugs or additions, and make sure to update tests as appropriate. If you find a mistake in the docs, send a PR! Even the smallest changes help.

For major changes, open an issue first to discuss what you'd like to change.

If you found this project helpful, let the community know by giving it astar:👉⭐

Want to support the project? Feel free to grab me a coffee, which is my main source of fuel for development:

SeeLICENSE.md.