Custom Welcome Screen

[tsanyqudsi]

It would be nice if we could make our own welcome screen instead of the default one.

[ovidiuch]

This is a good idea and something I'm open to adding support for.

It could be added as a plugin, however this raises the barrier to entry a bit because you need to package a Cosmos plugin to change the home screen.

Another open is to select one of your fixtures as the welcome screen. Is this what you're envisioning?

Btw, you can already set an initial fixture in your Cosmos config, which will auto open when you load Cosmos. This isn't a complete solution as you'll still see Cosmos' welcome screen when you close the fixture, but it might provide some instant value for you.

[tsanyqudsi]

I do think a plugin would be nice, it does raise the barrier to entry but still a doable solution. Currently I'm using initial fixture but I like the idea of having a page that only shows once.

[ovidiuch]

Just pushed a change that exposes a homeOverlay UI plug that can be used to override the default welcome screen.

Haven't pushed a release yet but you can use it by installing the following canary version: 6.0.4-canary.2314a55.0 (make sure to install this version by using --exact or equivalent depending on your package installer of choice).

Here are the steps you need to take to create this plugin:

1. Create a home-overlay-plugin folder in your project.
2. Create home-overlay-plugin/cosmos.plugin.json:

{
  "name": "Custom Home Overlay",
  "ui": "dist/ui.js"
}

3. Create home-overlay-plugin/ui.tsx (or .jsx if you don't use TypeScript):

import React from 'react';
import { createPlugin } from 'react-plugin';

const { plug, register } = createPlugin({
  name: 'customHomeOverlay',
});

plug('homeOverlay', () => {
  return (
    <div
      style={{
        position: 'absolute',
        top: 0,
        bottom: 0,
        left: 0,
        right: 0,
        background: '#fff',
      }}
    >
      Hello World!
    </div>
  );
});

register();

4. Create a build step that compiles your TSX/JSX. Here is a minimal webpack example but feel free to replace with your bundler/compiler of choice, create home-overlay-plugin/webpack.config.js:

import path from 'path';
import { fileURLToPath } from 'url';

const pluginRoot = fileURLToPath(new URL('.', import.meta.url));
const entry = path.join(pluginRoot, 'ui.tsx');
const outputPath = path.join(pluginRoot, 'dist');

export default {
  mode: 'development',
  devtool: false,
  entry,
  output: {
    path: outputPath,
    filename: 'ui.js',
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'ts-loader',
        options: {
          compilerOptions: { noEmit: false },
        },
      },
    ],
  },
  externals: {
    'react-plugin': 'ReactPlugin',
    react: 'React',
  },
};

5. Build your package (webpack -c ./home-overlay-plugin/webpack.config.js in this case).
6. Start Cosmos and your plugin will do its thing. If you wish to publish this plugin as a package that you install as a dependency you'll need to specifiy it in cosmos.config.json. Otherwise if the plugin config file is within your Cosmos root it will be picked up automatically.

@tsanyqudsi Let me know how this works for you. Based on your feedback I'll make this the official way to override the home screen and publish documentation for this approach. Thanks!

[tsanyqudsi]

where do I get import { createPlugin } from 'react-plugin';

is it from here ?

[ovidiuch]

where do I get import { createPlugin } from 'react-plugin';

is it from here ?

Yes, that's the package. But you shouldn't bundle it with your plugin. react-plugin as well as react need to be externalized in order to reuse their copy exposed by the Cosmos UI host.

The key for that is the externals section in the webpack config I gave as example. This is also explained in the UI plugin docs here: https://reactcosmos.org/docs/plugins/ui-plugins#bundling

Another example:

react-cosmos/packages/react-cosmos-plugin-open-fixture/webpack.config.js

Lines 16 to 21 in 2314a55

	externals: {
	'react-dom': 'ReactDom',
	'react-plugin': 'ReactPlugin',
	react: 'React',
	'styled-components': 'StyledComponents',
	},

[tsanyqudsi]

it doesn't work.

Basically the plugin is detected, but it does nothing.

cosmos:cosmos: [Cosmos] Using cosmos config found at cosmos.config.json
cosmos:cosmos: [Cosmos] Found 2 plugins: Vite, Custom Home Overlay
cosmos:cosmos: [Cosmos] See you at http://localhost:5000
cosmos:cosmos: [Cosmos] Using vite config found at vite.config.ts
cosmos:cosmos: [Cosmos] Replacing vite index module at src\main.tsx

You can check the plugin here and the cosmos here

[tsanyqudsi]

Update :
Apparently Cosmos found the plugin but failed to get the script.

[Cosmos] Loading plugin script at C:\Users\[redacted]levon\packages\welcome\dist\index.cjs
playground.js:41       
GET http://localhost:5000/_plugin/C:/Users/[redacted]/levon/packages/welcome/dist/index.cjs net::ERR_ABORTED 404 (Not Found)

Most probably it's because of the monorepo setup. You think I should put an issue on this part ?

[ovidiuch]

@tsanyqudsi Monorepo setup should be ok.

Yeah, feel free to create an issue and I'll investigate what's wrong.

But before we do further investigation, is there a file generated at C:/Users/[redacted]/levon/packages/welcome/dist/index.cjs?

[tsanyqudsi]

My bad, the monorepo setup is fine, I screw up with cjs. Now the problem is with the externalized packages.

When I do external: ['react-dom','react', 'react-plugin] in my tsup config

it shows Uncaught TypeError: Failed to resolve module specifier "react-plugin". Relative references must start with either "/", "./", or "../".

But when I don't put the config

[Cosmos] Loading plugin script at C:\Users\phlac\Documents\levon\packages\welcome\dist\index.js
playground.js:44 [Cosmos] Failed to load plugin script C:\Users\phlac\Documents\levon\packages\welcome\dist\index.js
playground.js:45 ReferenceError: process is not defined
    at index.js:23:6392
    at index.js:1:210
    at index.js:42:13192
    at index.js:1:210
    at index.js:42:17143
    at index.js:1:210
    at index.js:52:2959

[ovidiuch]

Try installing react-plugin as a dev dependency of the Cosmos plugin package.

[tsanyqudsi]

I gave up lol. Maybe it's me or tsup that screw things up.

[ovidiuch]

@tsanyqudsi I don't think external in tsup does the same thing as externals in Webpack or vite-plugin-externals in Vite.

• With tsup externals end up as require('react') which doesn't work in the browser.
• In Webpack/Vite the result is window['React'] which is what you need in this case.

I advice you try my webpack example or convert it to Vite if you're more comfortable. Alternatively, you can just put this in your source code instead:

const { React, ReactPlugin } = window;

import { createPlugin } from ReactPlugin;

const { plug, register } = createPlugin({
  name: 'customHomeOverlay',
});

plug('homeOverlay', () => {
  return (
    <div
      style={{
        position: 'absolute',
        top: 0,
        bottom: 0,
        left: 0,
        right: 0,
        background: '#fff',
      }}
    >
      Hello World!
    </div>
  );
});

register();

But it's not as pretty as you need to convince TypeScript that React and ReactPlugin are attached to the global window object.

[tsanyqudsi]

Tried vite, somehow same result. I stumbled with the comment here so I installed webpack and it's working like a charm.

Based on my somehow headbanging experience, I do have few feedbacks.

import { createPlugin } from 'react-plugin';

const { plug, register } = createPlugin({
  name: 'customHomeOverlay',
});

plug('homeOverlay', () => {
  return (
    // content here
});

register();

1. That's nice. It's not a nightmare to build the welcome screen. However, the build process is the opposite. I'm running react-cosmos using vite and installing webpack and vite in the same monorepo is not a good DX for me.

2. It would be also nice if you provide a way to close the "All Fixtures" in the welcome screen and provide an API to navigate to the first fixture or any fixture listed ? This way, the welcome screen able to be "full width" if the person choose to do so.

3. The documentation needs to be more clear tho.

Oh, could you republish react-plugin someday ? I'm rebuilding my Visual Novel engine and i'm interested to use react-plugin since the idea is quite nice. :P

[ovidiuch]

so I installed webpack and it's working like a charm.

Looking good! :D

I'm running react-cosmos using vite and installing webpack and vite in the same monorepo is not a good DX for me.

Just remembered, here's an example of how someone else configured this using tsup: https://github.com/birchill/react-cosmos-dark-mode/blob/1b6667985a3d7aee7ddbecbf03a1b1acde3822fe/tsup.index.config.ts#L9-L15

So you might be able to get rid of webpack after all.

It would be also nice if you provide a way to close the "All Fixtures" in the welcome screen and provide an API to navigate to the first fixture or any fixture listed ? This way, the welcome screen able to be "full width" if the person choose to do so.

The last thing I want is to provide config options for small customizations like this. It will blow up the API surface area and introduce conflicts between features and between versions, etc.

That said, you can do everything you want using plugins. After all the entire Cosmos UI is just plugins plugging into plugins. So you could extend the left nav and hide it when a fixture isn't selected, etc. But it's not trivial as you need to get intimate with the built-in Cosmos plugins: https://github.com/react-cosmos/react-cosmos/tree/main/packages/react-cosmos-ui/src/plugins

I can help with pointers if you're interested in delving deeper but understand this isn't something well documented and it won't be obvious which slot to plug into or what methods you can call from what plugin. But each plugin has a clear spec like this one: https://github.com/react-cosmos/react-cosmos/blob/main/packages/react-cosmos-ui/src/plugins/FixtureTree/spec.ts so in theory it's not impossible to navigate the Cosmos UI internals on your own.

Oh, could you republish react-plugin someday ? I'm rebuilding my Visual Novel engine and i'm interested to use react-plugin since the idea is quite nice. :P

I want to make react-plugin open source some day but at the moment I am overwhelmed already and don't have time to maintain it as an independent project, receive API ideas, have to maintain backwards compatibility between versions, etc.

But that said the API is documented here https://reactcosmos.org/docs/plugins/ui-plugins and the Cosmos UI has been using this plugin API for years so it's pretty stable, too.

[tsanyqudsi]

Just remembered, here's an example of how someone else configured this using tsup: https://github.com/birchill/react-cosmos-dark-mode/blob/1b6667985a3d7aee7ddbecbf03a1b1acde3822fe/tsup.index.config.ts#L9-L15

Damn.. so I need to use esbuild plugin and makesure it's production lol.

You might want to add it to documentation someday. I think it's time to close the discussion. Will open a new one for customizing the welcome screen.