Gobstones Scripts is a CLI tool that helps in the creation of library projects for GobstonesWeb2 by hiding away the configuration files for several building tools, such as Typescript, Rollup, Jest, nps and Typedoc, and providing configuration files in your project root for others.
It also allows to execute scripts using this hidden configuration. Configurations may be overwritten at any time to provide more functionality, but defaults tend to work on most cases.
You may think of gobstones-scripts as some sort of create-react-app + react-scripts for the Gobstones Project libraries. The main idea is to allow
newcomers to the project to easily maintain and create new libraries and
modules, retaining the guidelines of the Gobstones organization.
This library adds a binary file that can be executed as a CLI.
There are two ways in which you can install gobstones-scripts, globally or locally.
The global install allows to execute the gobstones-scripts command globally, by installing the CLI to your path.
The best thing about it is the ability to create new projects or to initialize a project in a specific folder. To install globally with npm run
npm install --global @gobstones/gobstones-scripts
You do not need the global installation in order to use gobstones-scripts in a project, but it's useful if you are starting a project from scratch. If you are not planning to create new projects, we recommend to stick with the second method instead.
To install locally to your already created project run the following with npm.
npm install --save-dev @gobstones/gobstones-scripts
This will add gobstones-scripts as a dependency to your project. This is
useful to use gobtones-scripts as a wrapper for configuration files and
executing nps commands in your project. Almost all projects in GobstonesWeb2
use this method, and the project is already added as a dependency that will get
installed when running npm install on it.
The common usage is to run gobstones-scripts as a CLI tool, by running directly in the following way if you installed globally
gobstones-scripts
or through npx if installed locally.
npx gobstones-scripts
If you have created a project through this tool, you already have a script in
your package.json file to run the tool, gbs. Just run the script via your
package manager:
npm run gbs
Run the command always from the root of your project in order to execute local commands.
The CLI is divided into a main command and multiple sub-commands.
The main command is useful for getting usage help. Run the command without any flags to get information about the different options. Useful flags include:
-h --help: display help for command-v --version: output the version number-c, --config: display the tool's detected configurationUtilities happen through sub-commands:
The commands create an init are used to create or configure new projects.
The create command is expected to be executed at any directory, and will
create a new folder with the project name that will hold your project. On the
other hand, init will initialize the project in the current directory, thus,
expecting the same to be empty.
create [options] <project-name>: create a new project with the given
project name.init [options]: initialize a project in the current folder.A <project-name> is any valid project identifier, that is, any string that i
valid folder name and contains no spaces.
Valid options include:
-t, --type <project-type>: the project type to create, one of Library,
CLILibrary, ReactLibrary, NonCode (default: "Library")-p, --package-manager <package-manager>: the project manager to use, one
of npm, yarn, pnpm(default: "npm")-s --silent: run silently, not displaying the tool's banner (default:
false)-D, --debug: run in debug mode, printing all the internal tool's
processing (default: false)-T, --test: run using verdaccio as a registry (default: false)-h, --help: display help for commandA special mention is to be held for the -T flag, which is not
self-explanatory. See the Manually testing newer versions of the library
section in order to better understand what this flag does.
Some common examples may be:
gobstones-scripts create -t reactLibrary my-react-library
gobstones-scripts init -t cliLibrary
The update sub-command is intended to update the project's configuration files
that live at the root of the project. This command is intended to be executed
inside an already created project.
update [options]: update the root files of the project.The command has the following options.
-i, --items <item> : the items to update. One of all, husky, github,
vscode, license, contributing, editorconfig, prettier, npm,
eslint, git, commitlint (default: all)-t, --type <project-type>: the project type to create, one of Library,
CLILibrary, ReactLibrary, NonCode (default: "Library")-s --silent: run silently, not displaying the tool's banner (default:
false)-D, --debug: run in debug mode, printing all the internal tool's
processing (default: false)-T, --test: run using verdaccio as a registry (default: false)-h, --help: display help for commandBy default, all root files are updated, but through the -i flag a specific
file can be updated. -i flag expects only one file at a time, that is, execute
as:
gobstones-scripts update -i npm
gobstones-scripts update -i eslint
and do not execute as:
gobstones-scripts update -i npm, eslint
Although you can specify the type of the project using -t, if the project was
created through gobstones-scripts, then the package.json will have a config
section with the project configuration, including the type of the project that
will be detected by the tool in case -t is not provided.
The eject sub-command allows you to eject the abstracted configuration files
of the project.
Some tools, like rollup, typedoc, and jest may have their
configuration files abstracted away, that is, these files live inside the
gobstones-scripts node_modules folder themselves, and not at the root of
your project. Most of the time, you will be fine with the provided default
configuration, but in occasions, you might need to set up a different
configuration for one of these tools for your project. This is where eject
comes in. By ejecting, the configuration files will be copied to the root of
your project, and these files will be used instead of the ones in the
gobstones-scripts folder. Note that usually you will not need to eject all
files, but only the one of a specific tool, use -i flag for that.
eject [options]: eject the configuration files of the project.This sub-command have the following options:
-i, --items <item> : The items to update. One of all, nps, rollup, typescript, typedoc, jest` (default: "all")-t, --type <project-type>: the project type to create, one of Library,
CLILibrary, ReactLibrary, NonCode (default: "Library")-s --silent: run silently, not displaying the tool's banner (default:
false)-D, --debug: run in debug mode, printing all the internal tool's
processing (default: false)-h, --help: display help for commandAn example will be:
gobstones-scripts eject -i rollup
Although you can specify the type of the project using -t, if the project was
created through gobstones-scripts, then the package.json will have a config
section with the project configuration, including the type of the project that
will be detected by the tool in case -t is not provided.
The run sub-command is used to execute a particular nps command through the
abstracted configuration provided by gobstones-script (except ejected files,
in which cae, the ejected configuration will be used).
run [options] [command] [...args]: run a command with nps.As you can see, you can call run with no options. In this case, the default
nps command will be executed. Else, you can provide a particular command (one
of the nps provided commands) and some arguments.
Available options include:
-t, --type <project-type>: the project type to create, one of Library,
CLILibrary, ReactLibrary, NonCode (default: "Library")-p, --package-manager <package-manager>: the project manager to use, one
of npm, yarn, pnpm(default: "npm")-s --silent: run silently, not displaying the tool's banner (default:
false)-D, --debug: run in debug mode, printing all the internal tool's
processing (default: false)-h, --help: display help for commandAvailable commands depend on project type, and can be found by executing the default action, as presenting the help is the default behavior for any project. Some common actions include
dev: run the project in development mode.build: build the project and output it to ./disttest: run the project's tests, generating coverage reports at
./coverage.test -- --serve: run the project's tests, generating coverage reports at
./coverage. and serve the generated folder in a local server.doc: build the documentation and output it to ./docsdoc -- --serve: build the documentation and output it to ./docs, and
serve the folder in a local server.lint: lint the files in the project.lint -- --fix: lint the files in the project and fix all auto-fixable
errors.prettify: run prettier with auto-fix in all project files.clear: delete all auto-generated files.changelog: append the latest tag information to the changelog.See the Running commands using gobstones-scripts for more information.
The tool provides several project types. When running locally in a project, the
project type configuration and the package manager to be used is loaded from
package.json, in the config.gobstones-scripts section. When creating a new
project, this configuration is added by default. Be sure not to delete it on
modifications to the package.json file.
When running a command using gobstones-scripts the tool loads all configuration for the different tooling from one of two locations.
rollup.config.js
file in the root of your project, then that file is used to load the Rollup
configuration../node_modules/@gobstones/gobstones-scripts/config, and they should not be
modified by the end user. If you need changes over a default configuration,
you should eject that configuration file to the root of your project.Command are run using Google's zx library and custom script, located at the
.scripts folder in the root of your project. The files starting with
underscore are internal and provide basic running functionality, the rest are
the actual scripts you can run.
You may modify the scripts if needed, although in most scenarios is not
required. You may also add custom commands by just creating a .ts file at this
folder with the name of our command.
If you have created a project from scratch with gobstones-scripts then you can run command by just calling:
npm start <command>
If no command is provided, the tool prints all the available commands and help. So in example, if you want to run the tests, you may run:
npm start test
Or if you want to run the linter:
npm start lint
Note that some commands accept additional argument, such as --fix for the lint
command. If you are running through npm start note that you need to use --
to pass the arguments to the script, and not npm itself. So if you want to run
the linter with fix use:
npm start lint -- --fix
When running using gobstones-scripts the configuration files for the building
and running tools, such as Typescript compiler configuration, may live in your
projects root or be the default one, that lives in the gobstones-scripts
configuration folder in node_modules.
If you require the tool's detected configuration file you may import it from the
_helpers.ts file at the .scripts folder.
You can access the API by importing the module
import gobstones_scripts from '@gobstones/gobstones-scripts';
Typings are exported so it can be used in TypeScript without additional packages.
The API exposes the create, init, update, eject and run functions that
are explained in the CLI. It also provides access to the version and the
configuration through the config attribute.
You may read their documentation through the published API documentation.
By default gobstones-scripts it's intended to be used by npm as the package manager, which is included by default on your node installation.
Nonetheless, gobstones-scripts has been tested to work with yarn too. gobstones-scripts relies on a flat node_modules, in order to hide away packages, so pnpm will not work with this tool, although it does support it as an argument for easy extension in a near by future.
Some internal commands relay on calling npm install or npx, which are replaced to their counterparts in other package managers if gobstones-scripts is called through them.
To detect which package manager has been used, we relay on
npm_config_user_agent environment variable, which is populated when executing
through a package manager.
So if you run, i.e. yarn start instead of npm start the tool detects
yarn as your package manager, and replaces all internal usages of npm
install to yarn install.
By default, npm is used, although you can configure this by the gobstones-scripts key in your package.json.
Support may change in the future once corepack gets out of the experimental state.
The underlying technologies in use include
Other files copied to your project will include
Also a .github folder will configure GitHub actions, and a .vscode folder will configure your Visual Studio Code environment on first run.
Finally, other files included do not require special technologies, but are important, such as CHANGELOG.md, CONTRIBUTING.md, README.md and LICENSE, together with package.json.
This tool has a more complex system for updating the version than other
libraries, as not only the package.json version needs to be changed. As the
version needs to be updated in multiple places of the tool for everything to
work properly, an update-version script exists that does the job. This tool
need to be called in the following way:
npm start update-version <version>
Where <version> is a specific version using semantic versioning convention
(major, minor and patch). After calling the tool, the version will be updated
everywhere it`s required in the project.
The tool includes the scripts build and test to build and test the tool.
The build command performs a build action and generates the executable file
and all API files at the dist folder. Run it by calling:
npm start build
The test performs linting, and then it attempts to create a project of each
type available at test/.temp and run the basic command of dev, build,
test and doc in each created project. You may run it by calling:
npm start test
WARNING:
When running the tests, all the dependencies will be downloaded for each project. This requires internet connection, and may take a while. So don't panic if the test seems to be frozen for a few minutes.
Additionally, the tool attempts to use the latest version you just built, trying to accessing from the verdaccio server. So you have need to make sure the latest version is published at the local server by running verdaccio by running
npm start verdaccio. Read the next section for more information.
This tool relies heavily on the packaging system. In that sense, the library need to be published in order to be tested, which constitutes a problem, as it cannot be tested without publishing. For that, we make use of verdaccio. Verdaccio provides a private server, that acts as a repository, which can run locally. By running verdaccio locally, then the newer versions of the library can be tested using such server instead of having to publish to npm.
Firs, publish the script globally using npm link, so you have an easy way of
calling the tool.
You can then run the verdaccio server and publish the library to it by running:
npm start verdaccio
WARNING: Note that verdaccio expect that you have updated the version of the package to a number that is not used already, even in the npmjs registry. Be sure to update it before running the command.
While the server is still running, you can run the globally installed script,
adding the testing flag to any command (--test or -T). This flag instructs
the tool to search the library in the verdaccio server instead of npmjs
registry.
Additionally, it may happen that you are required to configure verdaccio locally. In such case, run the following command:
npm start verdaccio -- --serve
This will run the verdaccio server, but it will not attempt to publish the library. You should then configure the user and publish the library manually. First create a user in the server by running:
npm adduser --registry http://localhost:4567
Notice the httpasswd file inside the test/verdaccio folder, which containes
the users and their hashed passwords. If you forgot your password, you may
delete the contents of the file and start over. Remember that, as this is for
local testing only, you should stick with a simple username and password.
Something you may remember. By default we use the gobstones username with the
gobstones password.
Then login to the registry:
npm login --registry http://localhost:4567
After that, you should be able to publish your library by doing:
npm publish --registry http://localhost:4567
Once the verdaccio server is configured for the first time, you should be able
to stop it and then re-run and publish using the npm start verdaccio command.
See our Contributions Guidelines to contribute.