remix-run/remix-website

Remix Website

Contributing

If you want to make a contribution

• Fork and clone this repo
• Create a branch
• Push any changes you make to your branch
• Open up a PR in this Repo

Setup

First setup your .env file, use .env.example to know what to set.

cp .env.example .env

Install dependencies

npm i

Local Development

Now you should be good to go:

npm run dev

To preview local changes to the docs folder in the Remix repo, select "local" from the version dropdown menu on the site. Make sure you have the remix repo cloned locally and LOCAL_REPO_RELATIVE_PATH is pointed to the correct filepath.

We leverage a number of LRUCache's to server-side cache various resources, such as processed markdown from GitHub, that expire at various times (usually after 5 minutes). If you want them to expire immediately for local development, set the NO_CACHE environment variable.

NO_CACHE=1 npm run dev

Note that by default this assumes the relative path to your local copy of the Remix docs is ../remix/docs. This can be configured via LOCAL_REPO_RELATIVE_PATH in your .env file.

Preview

To preview the production build locally:

npm run build
npm run preview

Deployment

The production server is always in sync with main

git push origin main
open https://remix.run

Pushing the "stage" tag will deploy to staging.

git checkout my/branch

# moves the `stage` tag and pushes it, triggering a deploy
npm run push:stage

When you're happy with it, merge your branch into main and push.

Content

Authoring Blog Articles

• Put a markdown file in data/posts/{your-post-slug}.md
• Follow the conventions found in other blog articles for author/meta
  • Make sure your author name in the post is the same as the one in data/authors.yml
  • If you don't have an author photo yet, create one (the template is in Figma)
• Create and optimize any inline blog post image(s) and put them in /public/blog-images/posts/{your-post-slug}/{image-name}.{format}
  • @TODO convention for ensuring images are large enough for 1x/2x?
• Create a featured image for the post that shows up on the blog’s index page as well as at the top of each post. Put it in /public/blog-images/headers/{your-post-slug}.{format} (this gets referenced in the YAML front-matter for each post).
  • @TODO what is, or should be, the difference between this image and the social share image?

When linking to other posts use [name](article-slug), you don't need to do [name](/blog/article-slug)

Adding to Showcase

The Showcase page is a collection of sites built on Remix that are particularly impressive. If you think there is something missing from this list, feel free to open a PR for the team to review.

• Record quick demo of the website (~6s)
• Grab or screenshot the first frame of the video
• Add both resources to public/showcase-assets
• Run cd public/showcase-assets && ./convert.sh to convert images and videos to compressed formats
  • Warning: this script was created hastily with ChatGPT and little concern for others running it. Feel free to offer improvements to the script and/or documentation
• Remove/don't commit the original video and image
• Add new showcase example data to showcase.yaml

Adding to Resources

The Resources page is a collection of templates and libraries that make building sites with Remix even easier. For now this data is driven by a yaml file, but eventually we anticipate replacing it with a database.

If you would like to contribute a new resource to these pages, simply add it to resources.yaml

CSS Notes

You'll want the tailwind VSCode plugin fer sure, the hints are amazing.

The color scheme has various shades but we also have a special "brand" rule for each of our brand colors so we don't have to know the specific number of that color like this: <div className="text-pink-brand" />.

We want to use Tailwind's default classes as much as possible to avoid a large CSS file. A few things you can do to keep the styles shared:

• Avoid changing anything but the theme in tailwind.config.js, no special classes, etc.
• Avoid "inline rules" like color-[#ccc] as much as possible.
• Silly HTML (like a wrapper div to add padding on a container) is better than one-off css rules.

Algolia Search

We use DocSearch by Algolia for our documentation's search. The site is automatically scraped and indexed weekly by the Algolia Crawler.

If the doc search results ever seem outdated or incorrect be sure to check that the crawler isn't blocked. If it is, it might just need to be canceled and restarted to kick things off again. There is also an editor in the Crawler admin that lets you adjust the crawler's script if needed.

remix-website's Issues

Redirect to main branch when only lang slug is present

From user Alem Tuzlak on Discord:

Just a small suggestion for the remix docs, it would be cool if i went to remix.run/docs/en it would redirect me to the latest version or the main one of the docs instead of me hitting an error boundary. if you go to remix.run/docs it goes to => remix.run/docs/en/main but if you go to remix.run/docs/en it enters an error boundary

https://discord.com/channels/770287896669978684/770287896669978687/1110137964090101760

Expected Behavior:
https://remix.run/en -> redirects to https://remix.run/en/main

"Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node." on https://remix.run/

See remix-run/remix#2943

Create meta tag helper function

Would be nice to have a common set of meta tags that we can use/extend. Maybe just a simple function with some defaults.

The main page (_marketing._index.tsx) has a nice set of defaults

export const meta: MetaFunction<typeof loader> = (args) => {
  let { siteUrl } = args.data || {};
  let title = "Remix - Build Better Websites";
  let image = siteUrl ? `${siteUrl}/img/og.1.jpg` : null;
  let description =
    "Remix is a full stack web framework that lets you focus on the user interface and work back through web standards to deliver a fast, slick, and resilient user experience. People are gonna love using your stuff.";
  return metaV1(args, {
    title,
    description,
    "og:url": siteUrl,
    "og:title": title,
    "og:description": description,
    "og:image": image,
    "twitter:card": "summary_large_image",
    "twitter:creator": "@remix_run",
    "twitter:site": "@remix_run",
    "twitter:title": title,
    "twitter:description": description,
    "twitter:image": image,
  });
};

I think we could possibly just extend this.

Admin token interface

Make a button to create tokens for any random github account, free for our employees/friends/ourselves, or if somebody purchased and there was an error.

When done, give Lennart a license

Render Changelog on the Website

Our Changelog doc is sad

This was a temporary addition, but we would really prefer to render the full doc on our website. Just a matter of fetching the correct file on that specific route instead of what's in the docs.

Remove unused package `dotenv-cli`

It looks that the development dependency dotenv-cli is unused. A grep through the repository didn't show matches. However I understand it's a CLI tool to run the project with different or even combine .env files.

While I don't see any reason for this dependency, if there's some valid use, then it should be documented.

package.json uses it for the preview script:

    "preview": "cross-env NODE_ENV=production dotenv node server.mjs",

But we already have dotenv setup on vitest.config.mts, so it seems is not doing any useful work there. Or at least I cannot see it after reading the package documentation.

Blog on mobile looks terrible

Too much margin and the font is kinda big. FIx it.

Upgrade website to v0.13

Deploy websites with GH Actions

Add types/validation for matches

useMatches and other cases of matches don't supply any types. With the v2 upgrade, this ended up causing TS to start failing. Added a bunch of @ts-expect-error statements with the intention of coming back and fixing them

If using zod makes this easy, that's great since we already have it in this project. However, avoid using it in any data that ships to the client (so server-side only)

Fetch docs from github, use new syntax highlighter

Issues cleanup

All issues but #66 should be closed as they are not applicable anymore.

#19 can be kept open too if you want to enhance the error message, but there's a proper error boundary now.

Can view repo - Not purchased.

Hey! I was interested in remix and browsed around. After I saw your tweet: https://twitter.com/remix_run/status/1321470965134471171 I did the following:
Clicked buy on the indie license,
Logged in with Github,
Loaded the stripe purchase page, but then backed out (not paying),
loaded remix.run/dashboard and I can see the docs while also having an invite to collaborate here.

Hopefully, if this is not intentional you can catch it early!

Add loading indicator to top nav

A suggestion from @brophdawg11

we should add some form of loading indicators to the top nav (Docs, Blog, Showcase, Resources). I clicked on one that didn't have a cache entry so it took ~1-2s and there's no visual feedback that my click did anything

Add navigation from docs back to main home page

Right now you can't get back to the home page on the docs site. The logo takes you to the root of the docs, which is sometimes nice, but maybe not what you'd expect (especially if you came from the home page)

Edit link referencing RR website

This line

remix-website/app/routes/docs/$lang.$ref.tsx

Line 747 in 6e9127a

let repoUrl = "https://github.com/remix-run/react-router";

Should be

-  let repoUrl = "https://github.com/remix-run/react-router";
+  let repoUrl = "https://github.com/remix-run/remix";

For some reason, I can't create a PR, so that's why I'm posting this issue

update vertical alignment of "Docs Navigation" in mobile header

See remix-run/remix#5291

Pricing page updates

• Price going up to $1,200 for commercial
• What "beta" means
  • We don't anticipate any more API changes
  • Now is a good time to get in and help us get it stable
  • Should be stable in a few weeks, work now can be deployed confidently then!

Add more template data

Need to add at least 20 templates to the templates.yaml file

A few other niceties to add in this one

• Validate with zod
• Add featured or something similar as a flag to determine which template is featured

Support multiple authors in meta image tags

Right now we only support uploading only one author to Cloudinary for our meta images

So for Remix ❤️ Vite we just have Pedro

I believe this is just because we only allow a single author to be passed

Add customers discuss repo again

rework license invitation to use a token instead of the license key as the invite token

email new purchases the registration url after a purchase

Update quick start docs to match the starter template

• do it in typescript
• make a very clear note to use the no-ts branch for JS only

Dark mode via system preferences is not persistent across navigations

As you can see, dark mode via system preferences does not persist well

crazy-dark-mode.mov

I believe it's due to this script, which can get unsynchronized on navigation changes.

check for stripe customer ID before additional purchases

Otherwise stripe creates more customers w/ the same email!

Pull Template data from GitHub

Need to pull the following data from GitHub for the templates

• description
• tags
• stars
• sponsor URL (if exists)

Will want to leverage server cache so we aren't constantly re-fetching this data. Will need to figure out a good strategy for fetching all of the templates, filtered templates, and individual templates. Ideally we want to use the same cache for each of these, and maybe a separate one or separate key for the README (for template slug pages)

Fix display dates on blog posts

The display dates seem to be off by 1 on our blog posts, which is no good. Probably just some faulty logic somewhere

Upgrade rehype, remark, and related dependencies

The following packages needed to be bumped to the latest major versions:

• rehype-autolink-headings
• rehype-slug
• rehype-stringify
• remark-gfm
• remark-html
• remark-parse
• remark-rehype
• unified
• unist-util-visit

I upgraded them, deployed, and everything seemed to work fine. However, I got some type errors and am not familiar enough with these packages or the setup to quickly fix it. I figured this might be an issue someone else would be eager to dig their hands into

No HTTPS Redirects for `remix.run` on Safari

What version of Remix are you using?

N/A, issue is with remix.run site

Are all your remix dependencies & dev-dependencies using the same version?

• Yes

Steps to Reproduce

For the remix.run site and all routes under it (i.e. /docs), there aren't automatic redirects to HTTPS in Safari for both macOS and iOS.

So typing in remix.run or remix.run/docs in the address bar leads me to http://remix.run or http://remix.run/docs which causes a "Not Secure" badge to be shown.

I tried it in Chrome and it did direct me to the HTTPS version, so not too sure if it's a Safari only bug or a feature of Chrome, though I didn't have forced redirects to HTTPS turned on in Chrome.

Expected Behavior

I expected the site to be redirected to the HTTPS version on every browser/platform.

Actual Behavior

On Safari across all devices (both up to date), the site hasn't been performing forced redirects to the "securely" connected site for months.

Here's a link to a screen recording to demonstrate what I'm seeing on my end.

I do know Kent mentioned in a podcast that Remix.run is hosted on Fly.io, and in case it's not just a Safari issue, just wanted to help out and throw in some helpful things I found on Fly's website.

There's an [http_service] section of the fly.toml that has a force_https flag that can be enabled, i.e.:

# /fly.toml
[http_service]
  force_https = true

Though it only works for Apps_V2 servers that are only using HTTP/HTTPS services.

Or, you can use the services.ports section in whichever service's section that's being used to serve the site, i.e.:

[[services.ports]]
  force_https = true

Or, you can use Express middleware to handle it for you, per Fly.io's blog post:

app.use (function (req, res, next) {
    if(req.get("X-Forwarded-Proto")=="http") {
            // request was via http, so redirect to https
            res.redirect('https://' + req.headers.host + req.url);
    } else {
        next();
    }
});

Thanks for all you guys are doing in the React space! Super excited about HMR and HDR in v2. Cheers!

Bug: npm let us use undeclared (in package.json) dependencies

Is there a serious showstopper reason to not be using pnpm yet?
(jump to the end to see about the bug from the title of this issue)

• For all these excerpts, assume $ rm -rf node_modules/ has been run prior to the timed command.
• First run was without lock file and second run was always with lock file.
• Verification made while standing on HEAD, which currently is commit f54dbcd

npm

First run: ~55 seconds

$ time npm ci

added 1261 packages, and audited 1262 packages in 54s

10 vulnerabilities (9 moderate, 1 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

real    0m54,574s
user    0m18,137s
sys     0m15,546s

Second run: ~20 seconds

$ time npm ci
[redacted...]
real    0m19,637s
user    0m11,526s
sys     0m8,368s

pnpm

First run: ~40 seconds

$ time pnpm i
Packages: +1168
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 1232, reused 1167, downloaded 0, added 1168, done

[redacted...]

Done in 39.5s

real    0m39,637s
user    0m16,913s
sys     0m14,826s

Second run: ~3 seconds

$ time pnpm i
[redacted...]
Done in 2.7s

real    0m2,802s
user    0m8,708s
sys     0m2,670s

yarn

First run: ~113 seconds

$ time yarn install
yarn install v1.22.21
info No lockfile found.
[1/5] Validating package.json...
[2/5] Resolving packages...
[3/5] Fetching packages...
[4/5] Linking dependencies...
warning "@docsearch/react > @algolia/[email protected]" has unmet peer dependency "@algolia/client-search@>= 4.9.1 < 6".
warning "@docsearch/react > @algolia/autocomplete-core > @algolia/[email protected]" has unmet peer dependency "search-insights@>= 1 < 3".
warning "@docsearch/react > @algolia/autocomplete-core > @algolia/[email protected]" has unmet peer dependency "@algolia/client-search@>= 4.9.1 < 6".
warning " > @remix-run/[email protected]" has unmet peer dependency "@remix-run/server-runtime@^1.15.0 || ^2.0.0".
[5/5] Building fresh packages...
success Saved lockfile.
Done in 112.08s.

real    1m52,302s
user    0m17,545s
sys     0m4,605s

Second run: ~7 seconds

$ time yarn install

Done in 6.84s.

real    0m7,085s
user    0m8,749s
sys     0m10,127s

Other considerations

• npm requires audit
npm shows "10 vulnerabilities (9 moderate, 1 high)". After running npm audit fix we are left still with "9 moderate severity vulnerabilities". Finally npm audit fix --force gets ride of all the warnings, however it requires further analysis as some packages needed a SemVer major change.

  pnpm produces a clean installation without warnings. However after installing I run pnpm audit just in case, and it found only one vulnerability:

$ pnpm audit
[redacted]
moderate │ xml2js is vulnerable to prototype pollution

• yarn leave us with "unmet peer dependencies"

• both yarn and npm let us use undeclared dependencies
  Whether we install and run with yarn or npm, the server starts and runs ok. However, if we install our dependencies with pnpm, and run the server, we encounter this bug:

Error: Cannot find module 'react-router-dom' imported from 'app/routes/docs.$lang.$ref.tsx'

This happens because the way both yarn and npm resolve peer dependencies, which is wrong, as it let us use packages that we haven't explicitly declared in our package.json.

I vote we jump head first to start using pnpm. If no arguments against are given, I'll do the PR.

Add error handling/good fallbacks for Resource data

Either add error messages/clear defaults when certain data doesn't load, or improve the error message shown. These are all the data fetching that needs to be handled:

• resources.yaml -- Can probably default to the main error page if this fails
• fetchReadme/getResourceReadme -- Individual resource page, show a message that the readme can't be loaded properly with a link to the repo
• image fails to fetch -- better fallback than a broken image
• getSponsorUrl -- Maybe just don't show the sponsor button if this one fails? I think this one actually works this way already
• fetchResourceGitHubData/getResourceGitHubData -- Maybe some good fallbacks, such as "failed to load description". I think this is better than the whole thing blowing up

Cursor is pointer on algolia search modal in docs website

What version of Remix are you using?

remix.run

Are all your remix dependencies & dev-dependencies using the same version?

• Yes

Steps to Reproduce

1. Access remix.run/docs
2. Click top left algolia search button.
3. Cursor is pointer on the modal.

Expected Behavior

Cursor is default on the modal.

Actual Behavior

Cursor is pointer on the modal.

Algoliasearch modal has [role=button] attribute.
When [role=button], cursor is pointer.
This class is set by TailwindCSS.

But algoliasearch don't set css for cursor.
So add css for cursor, fix that.

Ex.

.DocSearch-Container {
    cursor: auto;
}

Fix www redirections

http://www.remix.run and https://www.remix.run should both redirect to https://remix.run

Licensing / Convertkit Features

Stripe lets them cancel any time. We've got automations in convertkit to warn them (to avoid getting a bunch of refund requests after the fact)

• If they cancel within 3 months
  • Deactivate their license
  • Give a special message from the registry instead of just 404, like "Your license has expired, to renew go to https://remix.run/renew/:token"
  • Add convertkit refunded tag

Other cases need to put more thought in:

• cancel after refund period months

  • add convertkit tag
  • add version to license so they can't install passed it
  • remove from any cool education material when we have it if they no longer hold a current license

• renew

  • have endpoint to do it /renew/:key
  • add ck tag

• unused license

  • after some time add ck tag

• team member

  • add ck tag for broadcasts

Little encoding issue with Algolia Search

See how <Form> reads <Form>

Add search to mobile

Right now our search bar is inaccessible on mobile. However, ~20% of docs users are accessing the docs on mobile devices (all time analytics)

If if the number is less, it's worth figuring out a way to add the search bar for smaller screen sizes

Upgrade to Remix 2.6.0

Quoting from the blog post Open Sourcing the Remix Website

We invite you to explore and learn from the source code
...
Open sourcing our website allows us to provide a real-world Remix site to learn from

I believe that if one of the ideas is to provide a real-world working site, it would be better to do it with the latest version of Remix.

Currently the website is using 2.5.1

I haven't used Vite so far, I'm waiting for it to become stable-stable to start using it on my projects, but I don't mind giving it a shot if you need help with this upgrade. I love solving issues :)

Add combobox to templates page

It would be nice to have a combo box on the templates page that allows you to search different tags and possibly template names

Handle incomplete emails

https://twitter.com/theycallmejpo/status/1460382927745785859

Visual accessibility issues in the remix.run/docs site

Reproduction

1. Visit https://remix.run/docs/en/main/start/quickstart
2. Run an accessibility audit, such as with Lighthouse or axe Devtools

System Info

n/a

Used Package Manager

npm

Expected Behavior

Pages such as https://remix.run/docs/en/main/start/quickstart shouldn't have any web accessibility issues.

Actual Behavior

Scanning with axe DevTools finds two visual errors:

• Insufficient color contrast: folks with low color perception and/or poor hardware or lighting conditions might not be able to read...
  • ...in dark mode: the #666666 commented-out text (e.g. # install runtime dependencies)
  • ...in light mode: the #30ba2d light green commands (e.g. my-remix-app)
• Links indistinguishable without relying on color: the color contrast between link colors and regular body text similarly isn't enough for some folks to be able to see the difference...
  • ...in dark mode: between the #3992ff link text compared to #a4a4a4 body text
  • ...in light mode: between #1b6ef5 link text compared to #434343 body text

I haven't dug too deeply. There might be more insufficient color contrasts or other issues.

Some quick suggested remediations could be:

• Lightning the comments in dark mode to be more visually distinct
• Darkening the green text in light mode to be more visually distinct
• Adding an underline to link text, the way GitHub recently did for Markdown by default

Note that I'm not an accessibility professional and might have missed some issues. I'd be happy to send in a PR with these fixes or alternatives, but would recommend having a real professional go through a full site audit.

unusual scrolling issue with a screening effect on Mac Safari aswell as Chrome

See remix-run/remix#6127

Use actions instead of API routes, and redo checkout/registration flow to use username/password

associate github account w/ remix account, add to remix source code repo

blog - scroll is broken

See remix-run/remix#5276

Add ability to change from npm to yarn/pnpm

This suggestion came up in Discord

being able to choose between npn/yarn/pnpm/bun for the install command

I love the way shadcn/ui does this.

docs CSS doesn't load when navigating from homepage under certain circumstances

See remix-run/remix#1777

PS: Can't migrate the issue from remix-run/remix since remix-website is not a proposed target.

Switching theme scrolls to top

remix-run/remix#6291

Look into typesense

I've been curious about typesense as an alternative to DocSearch (what we use now). It would also be nice to add search to the react-router website, so curious if this is a good fit for that as well.

Would need to do a little spike work to see what's involved, if it's easier to use, and if it would be easy to migrate to

Add auth token endpoint for CLI auth flow

Instead of asking users to go copy/paste their auth token from the dashboard, it'd be neat if we could open the login/purchase page in the browser for them and then call back to a localhost URL with the auth token when they're done. So the new user UX flow would be:

• npm init remix
• open the web browser
• purchase a license
• init script gets the token and finishes