vue-query-builder
Project setup
yarn install
Requirement: node > v11
Compiles target library
yarn build-bundle
This will generate an importable JS VisualQueryBuilder
library in the dist
directory.
Run your tests
The basic command to run all tests is:
yarn test:unit
You can also use a watcher so that tests rerun automatically on a change:
yarn test:unit --watchAll
To run a single test file:
yarn test:unit path/to/yourfile.ts
Finally, you can deactivate typescript checks to run tests quicker:
yarn test:quick
This can be useful to accelerate your development cycle temporarily when
developing a new feature or fixing a bug. Under the hood, this will use the
babel-jest
transformer on typescript files instead of ts-jest
.
Lints and fixes files
yarn lint
Build the documentation
yarn build-doc
This will run typedoc on the src/
directory and
generate the corresponding documentation in the dist/docs
directory.
Run the storybook
Storybook uses the bundled lib, so all showcased components must be in the public API.
In one terminal:
yarn storybook:bundle --watch
In another:
yarn storybook
This will run storybook, displaying the stories (use cases) of UI components.
Stories are defined in the stories/
directory.
Customize configuration
Usage as library
Without any module bundler
<!-- Import styles --> <!-- Import scripts -->
With an ES module bundler (typically webpack or rollup)
;
By default, the CommonJS module is imported. If you prefer the ES module version, import
dist/vue-query-builder.esm.js
.
Styles
If your module bundler can also import CSS (e.g. via styles-loader
):
;
If you prefer to use Sass, you may import directly the scss:
;
This example makes use of the
~
syntax from webpack's sass-loader to resolve the imported modules.
API
Modules
See the documentation generated in dist/docs
directory
Styles
TODO: document here sass variables that can be overriden
Playground
The /playground
directory hosts a demo application with a small server that
showcases how to integrate the exported components and API. To run it, just
run:
yarn playground
which is basically a shortcut for the following steps:
# build the visual query builder bundle yarn build-bundle --watch# run the server and enjoy! node playground/server.js
Once the server is started, you should be able to open the
http://localhost:3000
in your favorite browser and enjoy!
The server.js
script reads the playground/playground.config.json
config file
to know which database should be queried or which http port should be used. If
you want to customize these values, either edit this json file or override each
available option on the commandline, e.g.
node playground/server.js --dburi mongdb://localhost:27018
You can also customize options through environment variables with the following
naming pattern VQB_PLAYGROUND_{OPTION}
, e.g.
VQB_PLAYGROUND_DBURI=mongdb://localhost:27018 node playground/server.js
You can use the default test dataset by loading the playground/default-dataset.csv
file. To do that, use the following command line:
node playground/server.js --reset
If you want to use a custom CSV file, use the defaultDataset
command line option:
node playground/server.js --defaultDataset my-dataset.csv --reset
If you don't have mongodb installed, you can use the --automongo
flag from the
command line. It will use
mongodb-prebuilt to download
(the first time) and run mongo 3.6.12
and then listen on the port guessed from
the --dburi
flag.