Contributing
Read the Readmeβ
Start by reading Vulcan NPM Readme for basic install information.
Then, the package.json list the typical commands you'd expect from an NPM library: build, test...
Recommended: use Jest and Storybook to test your codeβ
When adding feature to Vulcan or fixing bug, you'll want to run your code to test it.
- For components, you can run Storybook:
yarn run storybook
. Stories let you render components in a certain state, and even automate some operations on them using the "play" function. Documentation: https://storybook.js.org/ - For code, you can run unit tests with Jest:
yarn run test
oryarn run test <your-test-file-name>
. - For graphql operations, check
test/integration
folder: you can run a full Vulcan backend, similar to the backend running in Vulcan Next. You can even use an in-memory Mongo database.
Starter apps with UI like Vulcan Next may have their own specific Storybook and Jest setup.
Run cd starters/next
to move to the relevant folders.
Advanced: plug to another applicationβ
Using your local Vulcan NPM install within another local application, usually based on Vulcan Next, requires "linking". Linking means that instead of using the package from NPM, you'll tell your application to use the local version of the package. Linking is quite complex (see https://github.com/VulcanJS/vulcan-next/issues/104) so we use Yalc to simplify it as much as possible.
To sum it up:
- In Vulcan NPM,
yarn run build && yarn run publish:local
will publish all packages in the local Yalc registry - In your application,
yalc link @vulcanjs/graphql
will get the package from this local registry. The commandyarn run link:vulcan
will do this for all @vulcanjs packages - When you update code in Vulcan NPM, rerun
yarn run build && yarn run publish:local
. Your app will automatically reload with the new version.
A similar documentation exists in Vulcan Next project.
/!\ Next 12 is known to have issues with Yalc + ESM @see https://github.com/vercel/next.js/issues/35110
Yarn.lock for the starter appsβ
You cannot have a "yarn.lock" in Yarn workspaces, otherwise they are considered as "isolated" and you cannot benefit from Yarn anymore, it won't hoist your packages at the root.
Yet, you might want to generate a yarn.lock
for starters app at publication time.
We solve that using this plugin: []
- Install via
yarn plugin import https://raw.githubusercontent.com/JanVoracek/yarn-plugin-entrypoint-lockfiles/main/bundles/%40yarnpkg/plugin-entrypoint-lockfiles.js
- Run
yarn
- Copy the generated
yarn.remix.lock
in relevant folders - In your CI, rename them to
yarn.lock
. In Remix you can do that during the init step for instance. In Next you might require user to do this manually, or at server startup in a script.
Common issuesβ
No index.d.ts in distβ
You may end up with a build folder like this:
dist/mongo/...
dist/graphql/...
dist/your-package/...
instead of just having your package code.
You mistakenly imported local code from another package, like importing from ../graphql
instead of @vulcanjs/graphql
in @vulcanjs/mongo
. Find the culprit import and fix them will repair the build.
If your import are correct and you still have this issue, this also seems to unexpectedly affect "@vulcanjs/mongo/client" (client entrypoint) as well. In this case, set a false webpack alias for the faulty package (see react-hooks for instance)
Package self-referencing or leaking server codeβ
If build:types
refuses to overwrite a file, you might have wrongly imported "dist" in your code ; have a package
that references itself ; or leak some server code in a shared package.
Forgetting to include tests and stories in tsconfig.jsonβ
This is necessary to get the right typings in VS code. If you ever need to exclude them, eg to fasten the build, then create a dedicated tsconfig.build.json
for instance and live tsconfig.json
alone.
See this long standing VS code ticket/
If you want to specifiy the files to include in the build, look at tsconfig.build.json
instead. This is the file that will actually be used by ts-loader
.
TypeScript syntax not recknognized in end-applicationβ
You are importing non built code directly. Example:
error - /code/vulcan-npm/packages/next-material-ui/components/Link.tsx 10:5
Module parse failed: Unexpected token (10:5)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
| import MuiLink, { LinkProps as MuiLinkProps } from "@material-ui/core/Link";
|
> type LinkProps = NextLinkProps &
| MuiLinkProps & {
| activeClassName?: string;
You either forgot to call yarn build
or did a direct import (import foobar from "@vulcanjs/reac-hooks/some-not-built-file")
.
Code not updating during testβ
Don't forget to build the code. If you write a test for package "React Hooks", and discover and fix a bug in package "GraphQL", you'll need to rebuild the "GraphQL" package to get the freshest version.
Weird behaviour when linking with React, Apollo, Mongoose.β
Define Peer Dependencies correctly. Many packages have side effects that are problematic if you duplicate them. Those packages should be
peer-dependencies in the relevant package.json
. You may add them at the root of the project too in development.
Also, use Yalc to install local version of Vulcan NPM within another local app, see the README for more information.
#####Β Example with Mongoose
Make it a peer dependencyβ
In packages/mongo/package.json
:
peerDependencies: {
mongoose: "> 5"
}
The end application will have only 1 version of Mongoose thanks to this.
In ./package.json
:
devDependencies: {
"mongoose": "^5.10.16"
}