All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
.md / .mdx compilation. This attempts to spread the the work of transpiling mdx across multiple workers.Promise instances by calling them in the handler of a resolved promise.BREAKING Renamed the nostalgie/helmet runtime module to nostalgie/markup to better reflect its purpose: affecting the generated markup. The Helmet, HelmetProps and HelmetTags have been renamed to Markup, MarkupProps and MarkupTags, respectively.
As a reminder, the nostalgie/markup module is your one-stop shop to set the page title, meta tags or other markup-related features:
import { Markup } from "nostalgie/markup";
export function MyPage() {
return (
<>
<Markup>
<title>My page title</title>
</Markup>
<h1>My page</h1>
</>
);
}Improved typing and behaviour of the styled helper function.
Changed the CodeSnippets component to hide line numbers by default but to show them with an MDX annotation of lines or an boolean prop lineNumbers.
Also made various improvements to overflow and highlighting of lines in the CodeSnippets component.
For example, the following:
```js
console.log('hello world');
```Results in:
console.log('hello world');And the following:
```js lines
console.log('hello world');
```Results in:
console.log('hello world');Adds the code:<import_specifier> import syntax to import an instance of the <CodeSnippet /> component, wired up with the source code of the file to which the <import_specifier> resolves.
This is expected to be useful in documentation and tutorials so that such documents can refer directly to concrete examples instead of having to duplicate the code.
Example:
import Changelog from 'code:./CHANGELOG.md';
Here are the first 6 lines of our changelog, with the emphasis put on the 5th and 6th lines.
<Changelog toLine={6} emphasizeLines={[[5,6]]} />Fixed support for the styled function and custom components.
You can now do the following:
import { styled } from 'nostalgie/styling';
function MyComponent() {
return <h1>Hello world</h1>;
}
// Template string api
export const MyComponentRed = styled(MyComponent)`
color: red;
`;
// Object style api
export const MyComponentBlue = styled(MyComponent){
color: 'blue',
};Refactored how code blocks are rendered in .md and .mdx to use a new, internal <CodeSnippet /> component. This new component supports emphasizing certain lines. Instead of each code snippet having static react components created at build time, this approach compiles a json representation of the snippet and styling information that a shared <CodeSnippet /> component consumes at runtime.
Code blocks now support chosing different themes for each code block. Themes can either be chosen from one of the themes built into shiki (see here for a list of built-in themes). For example:
```ts theme:nord
function helloWorkd() {
return 'hello world';
}
```Produces:
function helloWorkd() {
return 'hello world';
}This feature also supports loading themes from relative (to the .md or .mdx file) or absolute paths. For example:
```ts theme:./themes/OneDark.json
function helloWorkd() {
return 'hello world';
}
```Produces:
function helloWorkd() {
return 'hello world';
}Additionally, ranges of lines can be emphasized by using the emphasize meta option on code blocks. Multiple instances of the emphasize option can be used to highlight several ranges. For example:
```ts emphasize:2-4
function helloWorld() {
// For some reason,
// we decided to emphasize this comment
// and split it across 3 lines!?
}
```Produces:
function helloWorld() {
// For some reason,
// we decided to emphasize this comment
// and split it across 3 lines!?
}Added ability to gracefully recover from and log build errors in dev mode.
Add support for handling server-side redirects triggered by nostalgie/router's <Redirect /> component (via react-router).
Whereas before an app without redirects would be fully functional with JavaScript disabled, one with redirects would sit idle on any route intending to trigger a redirect. This change will result in a 302 response with a Location header and some (very) simple markup explaining the iminent redirect.
Add support for reading and embedding css resources referred-to by URLs.
For example, the following is now supported for loading a Google Font:
/* The following imports the Monoton font, with _just_ the letter N */
@import url('https://fonts.googleapis.com/css2?family=Monoton&display=swap&text=N');What is interesting about this is that the above url points to a css file, which also contains a URL @import to the actual font file. Nostalgie will import both of these, treating the font file as a base64-encoded uri. The resulting CSS file will be a stand-alone asset that no longer needs to download the font at runtime, avoiding any risk of flash of unstyled text (FOUT).
Of course, the trade-off here is that this increases the initial render size so it remains to be seen how this plays out.
@mdx-js/mdx to xdm for a smaller, faster MDX runtime.peerDependencies range for react and react-dom to correctly use the hard-coded ranges.@twind/shim/server now that it performs non-destructive edits to the markup apart from the class attribute values. Bonus: the markup parsing and augmentation is 50% faster.react, react-dom, @types/react-dom and @types/react-dom-server into peerDependencies using a range compatible with >= 16.8.0 or >= 17.0.0. It remains to be seen if putting the types in peer dependencies is beneficial or a point of friction.create-nostalgie-app templates. With this release, we include javascript and typescript.useQueryFunction hook with a Server Function. The hook is configured to keep the initial, server-rendered value for 5s and then cycle every 5s.create-nostalgie-app to use the JavaScript template.@twind/shim/server's shim() function because this was causing browser hydration warnings due to minor changes in whitespace.Change robots.text from Disallow: / to allowing everything but /.nostalgie endpoints. This is a temporary measure to allow Nostalgie sites to be crawled.
A likely future direction is to put this file totally in the hands of users via some ./public directory feature. The ./public directory approach seems to be the idiomatic solution in the wild. However, it's unclear if that's the best solution. Nostalgie will already copy and include assets referenced by JavaScript code in builds.
0.69.3.Fixed the orchestration of the different build steps so that the node server will not attempt to start until the SSR library is ready.
Also wired up the internal build throttling mechanism that was present but unused.
Bumped dependencies:
joi@17.4.0react-query@3.8.2JSON.stringify to encode initial boostrap data into the initial html markup. This is corrected by using jsesc to safely encode data for embedding in a script tag.Bumped dependencies:
react-query to 3.8.0.blob-polyfill to 5.0.20210201Added create-nostalgie-app, the easiest way to scaffold out a new Nostalgie project.
With a simple npx create-nostalgie-app my-app you have a fully-functioning Nostalgie app in less than 30 seconds.
Increased logging during build and forced clean exit upon completion.
There is some, as-yet-unknown handle keeping Node's event loop alive. To work around that, we're forcing exit via process.exit(0) when the build completes.
Switch to requirin npm@7 during development to prepare for using workspaces.
npm publish correctly in ./dist.nostalgie/internal/server to nostalgie/internal/renderer to better reflect purpose."pakage.json" as an explicit export in the package's export map. This makes it easier for tooling authors to identify the root of the locally-installed version of nostalgie and to figure out the modules' dependencies and version."dependencies" field and added "peerDependencies" for @types/react and @types/react-dom.devDependencies for packages like @mdx-js/react whose types are dependended upon by nostalgie packages / compiled types.Introduce nostalgie/styling as a module through-which to deliver a styled-components-like experience. Right now, this is built on twind and twind/css. (#12)
This PR introduces support for (typed) styling of intrinsic HTML elements a la styled-components with both the factory and explicit apis, respectively:
import { styled } from 'nostalgie/styling';
const Button = styled.button`
border: 1px solid rebeccapurple;
`;import { styled } from 'nostalgie/styling';
const Button = styled('button')`
border: 1px solid rebeccapurple;
`;Additionally, object syntaxes are supported, like:
import { styled } from 'nostalgie/styling';
const Button = styled({
border: '1px solid rebeccapurple',
});React JSX files no longer need to import * as React from 'react' as this will be injected automatically. Importing react in this way will have no harmful side-effects and may be considered optional. (#12)
tailwind.config.js file is found in the root of the project. (#12)twind from 0.12 to 0.14 and adjust internals accordingly../src/themes/OneDark.json theme file into the ./dist/themes/ folder at build time so that it is readable by the mdx compilation worker at build-time.@mdx-js/react and workerpool modules as install-time dependencies because we rely on being able to require.resolve() their files at build-time.Improved the internal wiring of the build pipeline so that no unnecessary work is performed and so that work will be running at maximum concurrency. (#10)
Add support for automatic browser reloads in nostalgie dev. This isn't 'hot reloading' (yet) but nevertheless provides a huge boost to developer ergonomics. (#10)
To opt out:
nostalgie dev --disable-hot-reloadIntroduce the --log-level flag for nostalgie dev and nostalgie build. (#10)
When authentication is configured, the cookies used to persiste ephemeral and long-lived session state will now always be Secure in production.
More precisely, whenever process.env.NODE_ENV is not "development", cookies will always be set with the Secure flag.
Added authentication support to nostalgie via the nostalgie/auth sub-package. (#7)
Nostalgie authentication currently provides for:
/.nostalgie/login?return_to and /.nostalgie/logout?return_to endpoints for logging in and logging out, respectively.ctx argument via the .auth property. High-level authentication status can be checked via ctx.auth.isAuthenticated and when the user is authenticated, their authentication details can be found on ctx.auth.credentials.user, ctx.auth.credentials.scope and ctx.auth.credentials.claims.useAuth() hook exported from nostalgie/auth. This hook returns the same form of authentication state as ctx.auth in server functions. It can be used, for example, to render a user avatar or make decisions about which routes are available to users.To configure authentication, the following environment variables must either all be set or none must be set (in which case the auth module is disabled):
AUTH_ISSUER - The OpenID issuer url, such as https://nostalgie.us.auth0.com. This URL will be used for automatic OpenID Connect discovery for further authentication configuration.
AUTH_CLIENT_ID - The OpenID client identifier for the application ('client') configured for your Nostalgie app.
AUTH_CLIENT_SECRET - The OpenID client secret for the application ('client') configured for your Nostalgie app. This is important to keep well protected. It will never be exposed to the front-end.
AUTH_COOKIE_SECRET - The secret used to encrypt session state in an Iron-encoded token.
Added support for importing .css files from JavaScript files. (#8)
Previously the return value of such imports was the url at which the generated CSS file could be found. The ergonomics of this were sub par; it wasn't possible to get Nostalgie to include these files in the initial page render so either there was a FOUC or a slower experience.
The community appears to have settled on the convention that importing a .css file should have the side-effect of causing that css to be injected into the DOM. Nostalgie picks up on this convention and will inject the CSS at runtime for lazy-loaded chunks and will inject the CSS during SSR for chunks referenced in routes activated by the current path.
Usage:
// Cause the styles in 'style.css' to be loaded into the DOM at the earlier of:
// 1. SSR page generation when the importing file is referenced in the initial route.
// 2. Immediately once a lazy chunk is loaded via `.lazy()`.
import from './style.css';kacl as a mechanism to lint and manage the changelog.gh-release to produce releases on GitHub.