Learn secco
Welcome to the secco tutorial! We’re excited you’re here.
The goal of this tutorial is to help you create a mental model for how secco works by trying it out in a demo project. Along the way, you’ll learn how to install secco, use its functionalities, and more!
Prerequisites
Before you can start the tutorial, follow these required steps:
- Install Node.js 18.19.0 or later
- Read the terminology guide
- Clone the secco-demo repository
Snippets for quicker cloning:
git clone git@github.com:lekoarts-demos/secco-demo.git
git clone https://github.com/lekoarts-demos/secco-demo.git
Afterwards, navigate to the newly created secco-demo
folder:
cd secco-demo
Install secco
As the first step, open your terminal and install secco globally:
npm install --global secco
Ensure that the installation was successful by running secco --help
. You should see an output similar to this:
➜ secco --helpUsage: secco <command>
Commands: secco init Initialize a new .seccorc file secco packages [packageNames...] Specify list of packages you want to link
How to use secco
In this part of the tutorial you’ll learn secco’s recommended workflow. This way you’ll get the most out of its functionalities and can apply it to your own projects later.
Inside the secco-demo
project two folders exist:
source
destination
This mirrors the use case that secco solves: You want to apply your unreleased, in-flight changes from your package(s) to a test project. secco can work on a single package or a monorepo of packages.
Time to start using secco! In these next couple of steps you’ll start the watch mode of your source compilation, initialize secco’s configuration file, and copy over any changes to your destination.
Start watch mode
When authoring a npm package you most often have to compile your source code to different formats. Either to support older formats like CommonJS or because you write your code in TypeScript. Either way, if you want to continuously copy over your changes to an example project, you need to run your bundler in watch mode. This tutorial uses tsup but your bundler will also have such an option.
-
Inside
secco-demo/source
install the required dependencies:secco-demo/source npm install -
Start the watch mode by running the
watch
script:secco-demo/source npm run watchYou should see a similar output to this:
secco-demo/source ➜ npm run watchCLI Building entry: src/index.tsCLI tsup v7.2.0CLI Using tsup config: /Users/name/secco-demo/source/package.jsonCLI Running in watch modeCLI Target: node16CLI Cleaning output folderESM Build startESM dist/index.mjs 138.00 BESM dist/index.mjs.map 223.00 BESM ⚡️ Build success in 34msCLI Watching for changes in "."CLI Ignoring changes in "**/{.git,node_modules}/**" | "dist"
For the rest of this tutorial keep this script running. In your own projects you should do the same. Once you edit the file secco-demo/source/src/index.ts
tsup will recompile it and output it into the dist
folder.
Initialize a .seccorc
file
Before running secco inside secco-demo/destination
it needs to know where to look for the source files. You can provide that information by creating a .seccorc
configuration file. On all consecutive runs of secco it’ll reuse that information.
You don’t have to create that file on your own as secco provides its own command for it.
-
Inside
secco-demo/destination
, run the following command in your terminal:secco-demo/destination secco init -
When the prompt asks, “What is the absolute path to your source?”, enter the absolute path to your source.
secco-demo/destination ? What is the absolute path to your source?✔ · /Users/name/secco-demo/source -
The prompt will show you a summary of what
secco init
will do. When the prompt asks, “Do you want to create the file?”, enter “Y”.
You should have a new .seccorc
file inside your secco-demo/destination
folder.
Start secco
Time to finally start secco! 🚀 Inside secco-demo/destination
run secco
:
secco
You should see an output similar to this:
➜ secco
WARN say-hello-world-secco does not seem to be installed and is also not published on npm. Error: No response or Non-200 response from https://unpkg.com/say-hello-world-secco@^1.0.0/package.json
[Verdaccio] Starting server...[Verdaccio] Started successfully!Publishing say-hello-world-secco@1.0.0-secco-1702634686296 to local registry...(node:18034) [DEP0106] DeprecationWarning: crypto.createDecipher is deprecated.(Use `node --trace-deprecation ...` to show where the warning was created)Published say-hello-world-secco@1.0.0-secco-1702634686296 to local registryInstalling packages from local registry: - say-hello-world-secco✔ Installation finished successfully!Copied package.json to node_modules/say-hello-world-secco/package.jsonCopied dist/index.mjs.map to node_modules/say-hello-world-secco/dist/index.mjs.mapCopied dist/index.mjs to node_modules/say-hello-world-secco/dist/index.mjs
A couple of things happened now, here’s the breakdown:
-
The first line warns that
say-hello-world-secco
isn’t installed and not published on npm. This is correct since you didn’t runnpm install
insidesecco-demo/destination
as it would’t have worked. After all,say-hello-world-secco
isn’t published yet. Therefore secco published the package to a local Verdaccio registry.You won’t see this warning if your package is already published to npm and you’re trying out a new version locally. In this instance you probably already installed the current latest version.
-
Once published to Verdaccio,
npm install
is run insidesecco-demo/destination
using the local registry. -
All package files are copied over
-
The
package.json
insidesecco-demo/destination
was changed to something like this:secco-demo/destination/package.json {"dependencies": {"say-hello-world-secco": "1.0.0-secco-1702634686296"},}This shows you that indeed secco installed the version from the local registry.
-
Tip: If you stop secco and start it again you’ll see that only files will be copied over. The reason is that the whole Verdaccio step is skipped if it’s not necessary, making the process faster!
Done! Keep the script running as long as necessary and enjoy the ease of use in the next step of this tutorial.
Edit your source
You reached the last part of the tutorial, great! Now that everything is set up, it’s time to see secco in action. You’ll be changing the source files and notice the before and after differences. The applied changes from source to destination will be near instantaneous.
-
Inside
secco-demo/destination
run thestart
script:secco-demo/destination npm run startYou should see this output:
secco-demo/destination ➜ npm run start> destination@1.0.0 start> node cli.mjsHello World! -
Open
secco-demo/source/src/index.ts
and edit the file:function sayHelloWorld() {console.log('Hello World!')console.log('Hello secco!')}export { sayHelloWorld } -
Inside
secco-demo/destination
rerun thestart
script:secco-demo/destination ➜ npm run start> destination@1.0.0 start> node cli.mjsHello secco!Great, it worked! 🎉
From now on every time you make a change to your source file it’ll be reflected inside your test project. Depending on your setup this will also work with hot reloading (so no restart of script/server necessary).
What’s next?
Browse the CLI reference: commands, config options, and flags. You can also check out the advanced guides like Continuous Integration.