[remix-gql-tailwind] Architectural review of current kit & showcase and any cleanup recommendations

[dustinsgoodman]

[tvanantwerp]

README

The README.md file contains only a minimum amount of information about Storybook and authenticating with GitHub. The majority of the file hasn’t been edited in 6 months. Doesn’t explain many things, e.g., Arc.

Storybook

Storybook is not officially supported by Remix yet. Since this starter’s initial implementation of Storybook, there’s been a great deal of detailed discussion about how Remix should support it here.

.env.example

Does not include all env variables required. Missing GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_GRAPHQL_ENDPOINT, and BASE_URL. The GITHUB_GRAPHQL_ENDPOINT in particular isn't likely to vary and may benefit from being included as a default value. Presently, the GraphQL client initialization file falls back to a localhost URL which doesn't do anything, causing errors.

Running the project

Could not even get the project to run. After adding necessary .env variables and clicking the Login with GitHub button, I ended up on an error screen. The login button correctly goes to GitHub, then returns to the correct /auth/github/callback route with the necessary codes. I used the same GitHub app credentials in .env as when I started work on the project six months ago. On redirect to the root / route, the server returns a 500 error. The CatchBoundary in root.tsx is used, but rendered as text rather than HTML. CLI states: Error: GraphQL Error (Code: 405).

The app didn't display correctly due to a missing GITHUB_GRAPHQL_ENDPOINT env variable, which was undocumented.

Storybook didn’t work properly, either. The mocks to replace with didn’t seem to be working as expected, and many components displayed errors as a result.

useHref() may be used only in the context of a <Router> component.

[tvanantwerp]

The function RepoNavigation, which somewhat confusingly is the sole and default export from a file named FileExplorerNav, is missing React keys.

[tvanantwerp]

These buttons do nothing.

[tvanantwerp]

Absence of http:// in profile websiteUrl causes links to render as relative to the app root. Adding http:// fixes this.

Problem

Fix

[tvanantwerp]

Similar to the user profile website link problem, the website links for repos are also set to be local. Replace the <Link> with <a>.

[tvanantwerp]

Mobile styles could use some polish.

[tvanantwerp]

Lots of components in the components directory, and names aren't always the easiest to figure out.

The contents of each of these components can be very different. Sometimes you might be looking for a specific component and not finding it because it's not top-level, but hidden inside another component's directory.

The existing hierarchy of components could probably be refactored for clarity.

Example:

components/
├─ Navbar/
│  ├─ A top-level component that is present on all pages
├─ Shared/
│  ├─ components used across other components, like styled buttons
├─ Profiles/
│  ├─ UserProfile/
│  │  ├─ various sub components go here
│  ├─ OrgProfiles/
│  │  ├─ etc...
├─ Repositories/
│  ├─ Header/
│  │  ├─ Navigation/
│  ├─ FileExplorer/
├─ ...

[tvanantwerp]

What minimal testing is set up in this starter itself either 1) doesn't exist, in the case of Vitest and yarn test, or 2) doesn't pass, in the case of local Cypress testing.

I'm trying to use the starter-wide Cypress tests, but so far no luck. Error:

[mock:*remix] Error: remix dev is not supported for custom servers.
[mock:*remix]     at Object.dev (/Users/tvanantwerp/Documents/thisdot/starter.dev-github-showcases/remix-gql-tailwind/node_modules/@remix-run/dev/cli/commands.js:262:11)
[mock:*remix]     at processTicksAndRejections (node:internal/process/task_queues:96:5)
[mock:*remix]     at dev (/Users/tvanantwerp/Documents/thisdot/starter.dev-github-showcases/remix-gql-tailwind/node_modules/@remix-run/dev/cli/run.js:183:3)
[mock:*remix]     at Object.run (/Users/tvanantwerp/Documents/thisdot/starter.dev-github-showcases/remix-gql-tailwind/node_modules/@remix-run/dev/cli/run.js:496:7)
[mock:*remix] npm run mock:remix exited with code 1

After consulting with @BrettZeidler he mentioned that Remix requires some special mocking for the Cypress tests to run. Remix is a special snowflake outlier of all the starters. I'm working on trying to get the mocks running locally.

[tvanantwerp]

I don't know what remix-gql-tailwind/server/index.js.map is or does—something to do with the arc deploy?—but it looks like the kind of auto-generated file that doesn't need to be in VCS.