| Title: | An Opinionated Framework for Using 'JavaScript' |
|---|---|
| Description: | Enforces good practice and provides convenience functions to make work with 'JavaScript' not just easier but also scalable. It is a robust wrapper to 'NPM', 'yarn', and 'webpack' that enables to compartmentalize 'JavaScript' code, leverage 'NPM' and 'yarn' packages, include 'TypeScript', 'React', or 'Vue' in web applications, and much more. |
| Authors: | John Coene [aut, cre] |
| Maintainer: | John Coene <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.3.9000 |
| Built: | 2024-11-03 05:28:26 UTC |
| Source: | https://github.com/johncoene/packer |
Add the clean-webpack-plugin to clean the bundled files.
add_plugin_clean(dry = FALSE, verbose = FALSE, clean = TRUE, protect = TRUE)add_plugin_clean(dry = FALSE, verbose = FALSE, clean = TRUE, protect = TRUE)
dry |
Whether to simulate the removal of files. |
verbose |
Write Logs to the console. |
clean |
Whether to automatically remove all unused webpack assets on rebuild. |
protect |
Whether to not allow removal of current webpack assets. |
Add the eslint-webpack-plugin run ESLint on files.
add_plugin_eslint()add_plugin_eslint()
Add the html-webpack-plugin to the configuration to generate HTML with webpack, used in packer to generate the UI of a golem app with webpack.
add_plugin_html(use_pug = FALSE, output_path = "../index.html")add_plugin_html(use_pug = FALSE, output_path = "../index.html")
use_pug |
Set to |
output_path |
Path to the generated html file, defaults to |
Add the prettier-webpack-plugin to prettify the pre-bundled files.
add_plugin_prettier()add_plugin_prettier()
Add the workbox-webpack-plugin to the config files.
add_plugin_workbox()add_plugin_workbox()
Apply Framework7 to a project, adds the relevant (babel) loader, installs dependencies,
and creates, or updates, or replaces the srcjs/index.js file.
apply_framework7()apply_framework7()
After running this function and bundling the JavaScript remember to place
div(id = "app"), tags$script(src = "www/index.js") at the bottom of your shiny UI.
Apply React to a project, adds the relevant (babel) loader, installs dependencies,
and creates, updates, or replaces the srcjs/index.js file.
apply_react(use_cdn = TRUE)apply_react(use_cdn = TRUE)
use_cdn |
Whether to use the CDN for |
After running this function and bundling the JavaScript remember to place
the code printed by the function in shiny UI. By default apply_react() does not
bundle react and react-dom and thus requires using reactCDN() to import the
dependencies in the shiny application: this function is created in a R/react_cdn.R.
Apply Vue to a project, adds the relevant (babel) loader, installs dependencies,
and creates, or updates, or replaces the srcjs/index.js file.
apply_vue(use_cdn = TRUE)apply_vue(use_cdn = TRUE)
use_cdn |
Whether to use the CDN for |
After running this function and bundling the JavaScript remember to place
div(id = "app"), tags$script(src = "www/index.js") at the bottom of your shiny UI.
Bundle and watch the JavaScript.
bundle(mode = c("production", "development", "none")) bundle_prod() bundle_dev() watch()bundle(mode = c("production", "development", "none")) bundle_prod() bundle_dev() watch()
mode |
The configuration mode tells webpack to use its built-in optimisations accordingly. |
bundle() - bundle the project.
bundle_prod() - bundle the project optimising production, equivalent to bundle("production") and npm run production.
bundle_dev() - bundle the project including debugging developer tools, equivalent to bundle("development") and npm run development.
watch() - watches for changes in the srcjs and rebuilds if necessary, equivalent to npm run watch.
Run checks on a package using packer.
checks()checks()
Output files are minified
put_precommit_hook is in place
put_rprofile_adapt is in place
Defines the engine to use with packer. One can pick between npm and yarn.
engine_set(engine = c("npm", "yarn")) engine_get() engine_adapt() engine_which()engine_set(engine = c("npm", "yarn")) engine_get() engine_adapt() engine_which()
engine |
The engine to use, npm or yarn. |
Generally one would want to define
the engine prior to scaffolding.
For convenience you can instead set the environment
variable PACKER_ENGINE to your engine of choice.
Packer reads this variable, all subsequent use
of packer will use the defined engine.
You can use the function usethis::edit_r_environ
to do so.
engine_set: Define the engine to use for the project.
engine_get: Retrieve the default engine.
engine_which: Retrieve which engine the project is set
to use-.
engine_adapt: Change the engine to match that of the
poject.
Check if the engine is correctly set up and prints helpful messages if not.
engine_check()engine_check()
Prints the output of the last npm command run, useful for debugging.
engine_console()engine_console()
Adds a Github Action to the package that will ensure JavaScript files have been bundled for production.
include_action_check()include_action_check()
Add the jsdoc plugin to generate documentation from JavaScript code with tags similar to roxygen2.
add_plugin_jsdoc(edit = interactive()) add_jsdoc_tutorial(name, edit = interactive())add_plugin_jsdoc(edit = interactive()) add_jsdoc_tutorial(name, edit = interactive())
edit |
Whether to open relevent file. |
name |
Name of tutorial |
Adds library settings to webpack config. This allow exporting JavaScript objects.
make_library(name = "[name]", type = "umd")make_library(name = "[name]", type = "umd")
name |
Name of the library, default recommended, see details. |
type |
Type of the library. |
The functions will be exported
at the specified name, e.g.: if
the name is myLib then functions can be
called with myLib.function();.
The default ([name]) means the name of the exported
library will be the same as the name of the scaffold.
This is advised because otherwise, if one has multiple
scaffold, an absolute will overwrite itself and only
the last scaffold added will be a valid library.
Functions to mock up packages for tests
tmp_package() tmp_golem() tmp_project() tmp_ambiorix() tmp_delete(tmp)tmp_package() tmp_golem() tmp_project() tmp_ambiorix() tmp_delete(tmp)
tmp |
A temp mock up project. |
Prints the output of the last npm command run, useful for debugging.
npm_console()npm_console()
Scan your project for vulnerabilities and automatically install any compatible updates to vulnerable dependencies.
npm_fix()npm_fix()
Runs npm audit fix
Install and uninstall npm packages.
npm_install(..., scope = c("dev", "prod", "global")) npm_uninstall(..., scope = c("dev", "prod", "global"))npm_install(..., scope = c("dev", "prod", "global")) npm_uninstall(..., scope = c("dev", "prod", "global"))
... |
Packages to install or uninstall. If no packages
are specified then this function install packages in
|
scope |
Scope of installation or uninstallation, see scopes. |
prod - Installs/Uninstalls packages for project with --save
dev - Installs/Uninstalls dev packages for project with --save-dev
global - Installs/Uninstalls packages globally with -g
Convenience function to run npm commands.
npm_run(...)npm_run(...)
... |
Passed to |
Roclet to run bundle_prod when documenting.
prod_roclet()prod_roclet()
Add a pre-commit hook that runs at every commit to ensure that JavaScript files are minified.
put_precommit_hook()put_precommit_hook()
Will only work if using git.
## Not run: put_precommit_hook() ## End(Not run)## Not run: put_precommit_hook() ## End(Not run)
Recommended checks for packer projects, runs put_rprofile_adapt and put_precommit_hook.
put_recommended()put_recommended()
Add engine_adapt() to .Rprofile.
put_rprofile_adapt()put_rprofile_adapt()
This is recommended so anyone contributing to the project is guaranteed to be on the correct engine.
Puts a testthat test to ensure the files are optimised for prod.
put_test()put_test()
This function adds packer to Suggests.
Creates the basic structure for an ambiorix application.
scaffold_ambiorix(vue = FALSE, use_cdn = TRUE, edit = NULL)scaffold_ambiorix(vue = FALSE, use_cdn = TRUE, edit = NULL)
vue |
Whether to include Vue, internally runs |
use_cdn |
Whether to use the CDN for react or vue dependencies,
this is passed to |
edit |
Automatically open pertinent files. Defaults to |
Only one of react or vue can be set to TRUE.
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_ambiorix() # move to package setwd(tmp) # scaffold ambiorix scaffold_ambiorix() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_ambiorix() # move to package setwd(tmp) # scaffold ambiorix scaffold_ambiorix() # clean up setwd(wd) tmp_delete(tmp) }
Creates a bare scaffold for no specific use case, as opposed to other scaffolds. This scaffold does not generate R code.
scaffold_bare(edit = NULL)scaffold_bare(edit = NULL)
edit |
Automatically open pertinent files. Defaults to |
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold bare scaffold_bare() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold bare scaffold_bare() # clean up setwd(wd) tmp_delete(tmp) }
Creates the basic structure for a shiny extension.
scaffold_extension(name, edit = NULL)scaffold_extension(name, edit = NULL)
name |
Name of extension used to define file names and functions. |
edit |
Automatically open pertinent files. Defaults to |
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_extension() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_extension() # clean up setwd(wd) tmp_delete(tmp) }
Creates the basic structure for golem app with JavaScript.
scaffold_golem( react = FALSE, vue = FALSE, framework7 = FALSE, use_cdn = TRUE, edit = NULL )scaffold_golem( react = FALSE, vue = FALSE, framework7 = FALSE, use_cdn = TRUE, edit = NULL )
react |
Whether to include React, internally runs |
vue |
Whether to include Vue, internally runs |
framework7 |
Whether to include Framework7, internally runs |
use_cdn |
Whether to use the CDN for react, vue or Framework7 dependencies,
this is passed to |
edit |
Automatically open pertinent files. Defaults to |
Only one of react, vue or framework7 can be set to TRUE. use_cdn is
not supported for Framework7.
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up golem project tmp <- tmp_golem() # move to package setwd(tmp) # scaffold golem scaffold_golem() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up golem project tmp <- tmp_golem() # move to package setwd(tmp) # scaffold golem scaffold_golem() # clean up setwd(wd) tmp_delete(tmp) }
Sets basic structure for a shiny input.
scaffold_input(name, edit = NULL)scaffold_input(name, edit = NULL)
name |
Name of input, will define internal name binding and CSS class. |
edit |
Automatically open pertinent files. Defaults to |
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_input() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_input() # clean up setwd(wd) tmp_delete(tmp) }
Creates the basic structure for leprechaun app with JavaScript.
scaffold_leprechaun(react = FALSE, vue = FALSE, use_cdn = TRUE, edit = NULL)scaffold_leprechaun(react = FALSE, vue = FALSE, use_cdn = TRUE, edit = NULL)
react |
Whether to include React, internally runs |
vue |
Whether to include Vue, internally runs |
use_cdn |
Whether to use the CDN for react or vue dependencies,
this is passed to |
edit |
Automatically open pertinent files. Defaults to |
Only one of react or vue can be set to TRUE.
TRUE (invisibly) if successfully run.
Sets basic structure for a shiny input.
scaffold_output(name, edit = NULL)scaffold_output(name, edit = NULL)
name |
Name of output, will define internal name binding and CSS class. |
edit |
Automatically open pertinent files. Defaults to |
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_output() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_output() # clean up setwd(wd) tmp_delete(tmp) }
Creates the basic structure for golem app with JavaScript.
scaffold_rmd(react = FALSE, vue = FALSE, edit = NULL)scaffold_rmd(react = FALSE, vue = FALSE, edit = NULL)
react |
Whether to include React, internally runs |
vue |
Whether to include Vue, internally runs |
edit |
Automatically open pertinent files. Defaults to |
Only one of react or vue can be set to TRUE.
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_project() # move to package setwd(tmp) # scaffold ambiorix scaffold_rmd() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_project() # move to package setwd(tmp) # scaffold ambiorix scaffold_rmd() # clean up setwd(wd) tmp_delete(tmp) }
Creates basic structure for a widget.
scaffold_widget(name, edit = NULL)scaffold_widget(name, edit = NULL)
name |
Name of widget, also passed to |
edit |
Automatically open pertinent files. Defaults to |
Internally runs htmlwidgets::scaffoldWidget() do not run it prior to this function.
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_widget() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold ambiorix scaffold_widget() # clean up setwd(wd) tmp_delete(tmp) }
Creates a scaffold for windy,
it's a modified version of scaffold_bare().
scaffold_windy(edit = NULL)scaffold_windy(edit = NULL)
edit |
Automatically open pertinent files. Defaults to |
TRUE (invisibly) if successfully run.
if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold bare scaffold_windy() # clean up setwd(wd) tmp_delete(tmp) }if (interactive()) { # current directory wd <- getwd() # create a mock up ambiorix project tmp <- tmp_package() # move to package setwd(tmp) # scaffold bare scaffold_windy() # clean up setwd(wd) tmp_delete(tmp) }
By default packer looks for the npm installation using
the which (or where) command.
This function lets you override that behaviour and
force a specific npm installation.
set_npm(path = NULL)set_npm(path = NULL)
path |
Path to npm installation to use. |
By default packer looks for the yarn installation using
the which (or where) command.
This function lets you override that behaviour and
force a specific yarn installation.
set_yarn(path = NULL)set_yarn(path = NULL)
path |
Path to yarn installation to use. |
Adds tests to a project, currently supports mocha and peeky, see details for more.
include_tests_mocha(esm = TRUE) include_tests_peeky() add_test_file(name) run_tests(open = FALSE)include_tests_mocha(esm = TRUE) include_tests_peeky() add_test_file(name) run_tests(open = FALSE)
esm |
Whether to install |
name |
Name of the test file to add, without extension. |
open |
Only valid for "peeky," this will open a development
UI if |
include_tests_mocha uses mocha and
mocha-webpack and
creates a directory called testjs where tests should be placed.
The function run_tests() will then uses mocha on all the files in
the testjs directory. All tests should end with .test.js.
include_tests_peeky uses peeky
it's very similar to mocha but also comes with a development UI
that can be accessed when running tests by setting open to
TRUE.
Requiring esm (esm = TRUE) is recommended as it will allow using the latest
ESM, e.g.: import in tests.
Install TypeScript types from npm.
ts_get_types(..., versions = NULL) ts_get_type(type, version = NULL)ts_get_types(..., versions = NULL) ts_get_type(type, version = NULL)
... |
Types to install. |
versions, version
|
Corresponding versions of types passed
to |
type |
Name of types |
ts_get_types: Flexible to retrieve multiple types.
ts_get_type: Convenience to easily retrieve a single type.
## Not run: ts_get_type("jquery") ## End(Not run) ## Not run: ts_get_types("@types/jquery") ## End(Not run)## Not run: ts_get_type("jquery") ## End(Not run) ## Not run: ts_get_types("@types/jquery") ## End(Not run)
Adds the loader for babel compiler to the loader configuration file.
use_loader_babel(test = "\\.(js|jsx)$", use_eslint = FALSE)use_loader_babel(test = "\\.(js|jsx)$", use_eslint = FALSE)
test |
Test regular expression test which files should be transformed by the loader. |
use_eslint |
Whether to also add the ESlint loader. |
The use_elsint argument is useful here as loaders have
to be defined in the correct order or files might be checked after
being processed by babel.
Excludes node_modules by default.
Adds the coffee-loader to use
cofeescript.
use_loader_coffee(test = "\\.coffee$")use_loader_coffee(test = "\\.coffee$")
test |
Test regular expression test which files should be transformed by the loader. |
Excludes node_modules by default.
Adds the file-loader
to resolve files: png, jpg, jpeg, and gif.
use_loader_file(test = "\\.(png|jpe?g|gif)$/i")use_loader_file(test = "\\.(png|jpe?g|gif)$/i")
test |
Test regular expression test which files should be transformed by the loader. |
Adds the Framework7 loader.
use_loader_framework7(test = "\\.(f7).(html|js|jsx)$")use_loader_framework7(test = "\\.(f7).(html|js|jsx)$")
test |
Test regular expression test which files should be transformed by the loader. |
Excludes node_modules by default. If used outside scaffold_golem
context, installs the babel-loader in the dev scope.
Adds the mocha-loader for tests.
use_loader_mocha(test = "\\.test\\.js$")use_loader_mocha(test = "\\.test\\.js$")
test |
Test regular expression test which files should be transformed by the loader. |
Excludes node_modules by default.
Adds the loader for the pug templating engine.
use_loader_pug(test = "\\.pug$")use_loader_pug(test = "\\.pug$")
test |
Test regular expression test which files should be transformed by the loader. |
Adds a loader rule that is not yet implemented in packer.
use_loader_rule( packages, test, ..., use = as.list(packages), .name_use = "use" )use_loader_rule( packages, test, ..., use = as.list(packages), .name_use = "use" )
packages |
NPM packages (loaders) to install. |
test |
Test regular expression test which files should be transformed by the loader. |
... |
Any other options to pass to the rule. |
use |
Name of the loaders to use for |
.name_use |
Depending on the webpack config
one might want to change the |
Reads the srcjs/config/loaders.json and appends the rule.
Installs loaders and adds relevant configuration rules
to srcjs/config/loaders.json, the function
use_loader_style is recommended.
use_loader_css(test = "\\.css$", import = TRUE, modules = TRUE) use_loader_sass(test = "\\.s[ac]ss$/i") use_loader_style(test = "\\.css$", import = TRUE, modules = TRUE)use_loader_css(test = "\\.css$", import = TRUE, modules = TRUE) use_loader_sass(test = "\\.s[ac]ss$/i") use_loader_style(test = "\\.css$", import = TRUE, modules = TRUE)
test |
Test regular expression test which files should be transformed by the loader. |
import |
Whether to enable |
modules |
Enables CSS modules and their config, a complex but powerful feature detailed here |
This will let you import styles much like any other modules, e.g.: import './styles.css'.
use_loader_css() - installs and imports css-loader packages as dev.
use_loader_style() - installs and imports style-loader and css-loader packages as dev. This loader enabled CSS modules.
use_loader_sass() - installs and imports style-loader, css-loader, and sass-loader as dev.
Add the loader svelte
use_loader_svelte(test = "\\.(html|svelte)$")use_loader_svelte(test = "\\.(html|svelte)$")
test |
Test regular expression test which files should be transformed by the loader. |
Adds the loader for the pug templating engine.
use_loader_ts(test = "\\.tsx?$")use_loader_ts(test = "\\.tsx?$")
test |
Test regular expression test which files should be transformed by the loader. |
Adds the Vue loader to the loader configuration file.
use_loader_vue(test = "\\.vue$")use_loader_vue(test = "\\.vue$")
test |
Test regular expression test which files should be transformed by the loader. |
Every time a new version of Vue is released, a corresponding version of vue-template-compiler
is released together. The compiler's version must be in sync with the base Vue package so that vue-loader
produces code that is compatible with the runtime. This means every time you upgrade Vue in your project,
you should upgrade vue-template-compiler to match it as well.
Creates PostCSS, and tailwindcss config files as well as adds the appropriate loaders and installs dependencies.
use_tailwind(test = "\\.css$")use_tailwind(test = "\\.css$")
test |
Test regular expression test which files should be transformed by the loader. |
Clean the cache
yarn_clean()yarn_clean()
The semver as a string.
## Not run: yarn_clean() ## End(Not run)## Not run: yarn_clean() ## End(Not run)
Prints the output of the last command run, useful for debugging.
yarn_console()yarn_console()
Installs or manage yarn globally.
engine_yarn_install() engine_yarn_set(version = "latest")engine_yarn_install() engine_yarn_set(version = "latest")
version |
Version to set yarn |
engine_yarn_install: Installs yarn globally.
engine_yarn_set: Set yarn function.
## Not run: engine_yarn_install() ## End(Not run)## Not run: engine_yarn_install() ## End(Not run)
Install and uninstall yarn packages.
yarn_add(..., scope = c("dev", "prod")) yarn_install() yarn_remove(..., scope = c("dev", "prod"))yarn_add(..., scope = c("dev", "prod")) yarn_install() yarn_remove(..., scope = c("dev", "prod"))
... |
Packages to install or uninstall. |
scope |
Scope of installation or uninstallation, see scopes. |
prod - Add/remove packages for project with no flag
dev - Installs/Uninstalls dev packages for project with --dev
## Not run: yarn_add("browserify") ## End(Not run)## Not run: yarn_add("browserify") ## End(Not run)
Find outdated dependencies
yarn_outdated()yarn_outdated()
## Not run: yarn_outdated() ## End(Not run)## Not run: yarn_outdated() ## End(Not run)
Convenience function to run yarn commands.
yarn_run(...)yarn_run(...)
... |
Passed to |
Upgrade yarn dependencies.
yarn_upgrade()yarn_upgrade()
## Not run: yarn_upgrade() ## End(Not run)## Not run: yarn_upgrade() ## End(Not run)
Get the version of npm.
Get the version of yarn.
yarn_version() yarn_version()yarn_version() yarn_version()
The semver as a string.
The semver as a string.
## Not run: yarn_version() ## End(Not run)## Not run: yarn_version() ## End(Not run)