0cd04fc882
## Issue
So, we've got an issue with our docs build not working. When building
for production, we get an error that looks a little bit like this:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 40.85s
TypeError: source_default(...).bold is not a function
TypeError: source_default(...).bold is not a function
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
Which isn't very helpful at all. If you go into
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` and modify
the `render` function to log the actual error and remove anything
chalk-related, you get this instead:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 44.62s
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38139:1593)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38513:1469)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Error: Unexpected: cant find current sidebar in context
Error: Unexpected: cant find current sidebar in context
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
That's better, but it's still not very clear.
## Getting more info
We've had problems with a similar error message before. Last time it was
caused by an empty file that docusaurus couldn't process.
A similar issue has also been described in [ this docusaurus GitHub
issue ](https://github.com/facebook/docusaurus/issues/7686). That's also
what gave me the idea of changing the logging in the dependency.
I'm currently unsure whether this is caused by the openapi docs or
something else. I've been in touch with the [openapi plugin
maintainer](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/323)
and he has been able to see the same error when building for prod
locally, but it was due to some old generated files.
Worth noting: this only seems to affect the prod build. Building for dev
(`yarn docusaurus start`) works just fine. It also fails locally **and**
in CI, so it _is_ an issue.
## Updating the logging
To get better logging, you can go into the
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` file and
update the `render` function from
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
// We are not using logger in this file, because it seems to fail with some
// compilers / some polyfill methods. This is very likely a bug, but in the
// long term, when we output native ES modules in SSR, the bug will be gone.
// prettier-ignore
console.error(chalk.red(`${chalk.bold('[ERROR]')} Docusaurus server-side rendering could not render static page with path ${chalk.cyan.underline(locals.path)}.`));
const isNotDefinedErrorRegex = /(?:window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
if (isNotDefinedErrorRegex.test(err.message)) {
// prettier-ignore
console.info(`${chalk.cyan.bold('[INFO]')} It looks like you are using code that should run on the client-side only.
To get around it, try using ${chalk.cyan('`<BrowserOnly>`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#browseronly')}) or ${chalk.cyan('`ExecutionEnvironment`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#executionenvironment')}).
It might also require to wrap your client code in ${chalk.cyan('`useEffect`')} hook and/or import a third-party library dynamically (if any).`);
}
throw err;
}
}
```
to
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
console.error(err)
throw err;
}
}
```
That'll yield the errors about the current sidebar in context.
## Root cause
Found the issue! 🙋🏼 It's explained in [this comment on the openapi docs
integration](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/323#issuecomment-1311549864)
for now, but in short: we have tags defined that we don't use. They're
being picked up by docusaurus, but don't have the proper context. That's
causing this.
The previously mentioned comment is included here for easy finding in
the future:
### Root cause explanation
The OpenAPI spec we use to generate the docs has a number of tags listed
at the root level. This is necessary for this plugin to pick up tag
categories and is, as far as I can tell, also how it _should_ be done.
However, not all of those tags are in use. Specifically, there's 2 tags
that are not.
When the plugin generates docs from the spec, it generates pages for all
endpoints and all tags and groups them by tag. However, it seems likely
that if a tag doesn't have any associated endpoints, then it won't get
added to the sidebar because there's no endpoint that references it.
But the doc files for these tags do end up lying around in the directory
regardless, and when docusaurus tries to pick up the files in the
generated directory, it also tries to pick up the unused tag files. But
because they're not part of a sidebar, they end up throwing errors
because they can't find the sidebar context.
### How I found it
The fact that I got more instances of the error message without the
sidebar ref than with it made me pay more attention to the number of
errors. I decided to check how many files were in the generated
directory and how many files were referenced from the generated sidebar.
Turns out the difference there was **2**: there were two generated files
in the directory that the sidebar didn't reference.
At this point, it was easy enough to try and delete those files before
rebuilding, and wouldn't you know: it worked!
### Our use case
Now, why do we have tags that are unused in the root spec? Can't we just
remove them?
That's a good question with a bit of a complicated answer. Unleash uses
an open core model and the OpenAPI integration is part of that open
core. The closed-source parts of Unleash are located in another repo and
extend the open-source distribution.
Because the OpenAPI spec is configured in the open-source part,
enterprise-only tags etc also need to be configured there. Then, when
the changes are absorbed into enterprise, we can use the tags there.
It gets more complicated because we use an enterprise instance to
generate the docs (because we want enterprise-endpoints to be listed
too). The instance uses the latest released instance of Unleash to have
the docs most accurately reflect the current state of things.
So, in this case, the tags have been added, but not yet used by any
endpoints, which suddenly causes this build failure. We can add the tags
to the enterprise-version, but the spec wouldn't be updated before the
next release regardless, which will probably be in a week or so.
This isn't an ideal setup, but .. it is what it is.
## Solutions and workarounds
As mentioned in the previous section, the reason the build was failing
was that there were unused tag files that docusaurus tried to include in
the build. Because they don't belong to a sidebar, the compilation
failed.
I've reported the issue to the openapi plugin maintainers and am waiting
for a response.
However, it seems that having unused root tags declared is invalid
according to the spec, so it's something we should look into fixing in
the future.
### Current workaround: cleaning script
The current workaround is to extend the api cleaning script to manually
remove the unused tag files.
### Ideal solution: filter root-level tags
Ideally, we shouldn't list unused OpenAPI tags on the root level at all.
However, because of the way we add root-level tags (as a predefined,
static lists, refer to `src/lib/openapi/index.ts`) and endpoints
(dynamically added at runtime) today, we don't really have a clear way
to filter the list of tags. This gets even more complicated when taking
the enterprise functionality and the potential extra tags they must
have.
This is, however, something that should definitely be looked into.
Working with OpenAPI across multipile repos is already troublesome, so
this is just yet another thing to look into.
|
||
|---|---|---|
| .do | ||
| .github | ||
| .husky | ||
| coverage | ||
| docker | ||
| docs/api/oas | ||
| examples | ||
| frontend | ||
| perf | ||
| scripts | ||
| src | ||
| website | ||
| .dockerignore | ||
| .editorconfig | ||
| .eslintignore | ||
| .eslintrc | ||
| .gitignore | ||
| .lycheeignore | ||
| .node-version | ||
| .nvmrc | ||
| .prettierignore | ||
| app.json | ||
| CHANGELOG.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| LICENSE | ||
| package.json | ||
| README.md | ||
| renovate.json | ||
| tsconfig.json | ||
| yarn.lock | ||
About Unleash
Unleash is an open source feature management solution. It improves the workflow of your development team and leads to quicker software delivery. Unleash increases efficiency and gives teams full control of how and when they enable new functionality for end users. Unleash lets teams ship code to production in smaller releases whenever they want.
Feature toggles make it easy to test how your code works with real production data without the fear that you'll accidentally break your users' experience. It also helps your team work on multiple features in parallel without each maintaining an separate feature branch.
Unleash is the largest open source solution for feature flagging on GitHub. There's 12 official client and server SDKs and 10+ community SDKs available; you can even make your own if you want to. You can use Unleash with any language and any framework.
Get started in 2 steps
1. Start Unleash
With git and docker installed, it's easy to get started:
Run this script:
git clone git@github.com:Unleash/unleash-docker.git
cd unleash-docker
docker compose up -d
Then point your browser to localhost:4242 and log in using:
- username:
admin - password:
unleash4all
If you'd rather run the source code in this repo directly via Node.js, see the step-by-step instructions to get up and running in the contributing guide.
2. Connect your SDK
Find your preferred SDK in our list of official SDKs and import it into your project. Follow the setup guides for your specific SDK.
If you use the docker compose file from the previous step, here's the configuration details you'll need to get going:
- For front-end SDKs, use:
- URL:
http://localhost:3000 clientKey:proxy-client-key
- URL:
- For server-side SDKs, use:
- Unleash API URL:
http://localhost:4242/api/ - API token:
default:development.unleash-insecure-api-token
- Unleash API URL:
If you use a different setup, your configuration details will most likely also be different.
Check a feature toggle
Checking the state of a feature toggle in your code is easy! The syntax will vary depending on your language, but all you need is a simple function call to check whether a toggle is available. Here's how it might look in Java:
if (unleash.isEnabled("AwesomeFeature")) {
// do new, flashy thing
} else {
// do old, boring stuff
}
Run Unleash on a service?
If you don't want to run Unleash locally, we also provide easy deployment setups for Heroku and Digital Ocean:
Configure and run Unleash anywhere
The above sections show you how to get up and running quickly and easily. When you're ready to start configuring and customizing Unleash for your own environment, check out the documentation for getting started with self-managed deployments, Unleash configuration options, or running Unleash locally via docker.
Online demo
Try out the Unleash online demo.
Community and help — sharing is caring
We know that learning a new tool can be hard and time-consuming. We have a growing community that loves to help out. Please don't hesitate to reach out for help.
💬 Join Unleash on Slack if you want ask open questions about Unleash, feature toggling or discuss these topics in general.
💻 Create a GitHub issue if you have found a bug or have ideas on how to improve Unleash.
📚 Visit the documentation for more in-depth descriptions, how-to guides, and more.
Contribute to Unleash
Building Unleash is a collaborative effort, and we owe a lot of gratitude to many smart and talented individuals. Building it together with community ensures that we build a product that solves real problems for real people. We'd love to have your help too: Please feel free to open issues or provide pull requests.
Check out the CONTRIBUTING.md file for contribution guidelines and the Unleash developer guide for tips on environment setup, running the tests, and running Unleash from source.
Contributors
Features our users love
Flexibility and adaptability
- Get an easy overview of all feature toggles across all your environments, applications and services
- Use included activation strategies for most common use cases, or use a custom activation strategy to support any need you might have
- Organise feature toggles by feature toggle tags
- Canary releases / gradual rollouts
- Targeted releases: release features to specific users, IPs, or hostnames
- Kill switches
- A/B testing
- 2 environments
- Out-of-the-box integrations with popular tools (Slack, Microsoft Teams, Datadog) + integrate with anything with webhooks
- Dashboard for managing technical debt and stale toggles
- API-first: everything can be automated. No exceptions.
- 12 official client SDKs, and ten community-contributed client SDKs
- Run it via Docker with the official Docker image or as a pure Node.js application
Security and performance
- Privacy by design (GDPR and Schrems II). End-user data never leaves your application.
- Audit logs
- Enforce OWASP's secure headers via the strict HTTPS-only mode
- Flexible hosting options: host it on premise or in the cloud (any cloud)
- Scale the Unleash Proxy independently of the Unleash server to support any number of front-end clients without overloading your Unleash instance
Looking for more features?
If you're looking for one of the following features, please take a look at our Pro and Enterprise plans:
- role-based access control (RBAC)
- single sign-on (SSO)
- more environments
- feature toggles project support
- advanced segmentation
- additional strategy constraints
- tighter security
- more hosting options (we can even host it for you!)
Architecture
Read more in the system overview section of the Unleash documentation.
Unleash SDKs
To connect your application to Unleash you'll need to use a client SDK for your programming language.
Official server-side SDKs:
Official front-end SDKs:
The front-end SDKs connects via the Unleash Proxy in order to ensure privacy, scalability and security.
Community SDKs:
If none of the official SDKs fit your need, there's also a number of community-developed SDKs where you might find an implementation for your preferred language (such as Elixir, Dart, Clojure, and more).
Users of Unleash
Unleash is trusted by thousands of companies all over the world.
Proud Open-Source users: (send us a message if you want to add your logo here)
Migration guides
Unleash has evolved significantly over the past few years, and we know how hard it can be to keep software up to date. If you're using the current major version, upgrading shouldn't be an issue. If you're on a previous major version, check out the Unleash migration guide!
Want to know more about Unleash?
Videos and podcasts
- The Unleash YouTube channel
- Feature toggles — Why and how to add to your software — freeCodeCamp (YouTube)
- Feature flags with Unleash — The Code Kitchen (podcast)
- Feature Flags og Unleash med Fredrik Oseberg — Utviklerpodden (podcast; Norwegian)
Articles and more
- The Unleash Blog
- Designing the Rust Unleash API client — Medium
- FeatureToggle by Martin Fowler
- Feature toggling transient errors in load tests — nrkbeta
- An Interview with Ivar of Unleash — Console
- Unleash your features gradually, slideshow/presentation by Ivar, the creator of Unleash