Skip to content

Commit ee54d24

Browse files
author
jared
committed
Added Typescript flake documentation
1 parent 889cfac commit ee54d24

File tree

3 files changed

+65
-8
lines changed

3 files changed

+65
-8
lines changed

flake-lang/build.nix

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -76,14 +76,11 @@
7676

7777
typescriptFlake = lib.mkOption {
7878
type = lib.types.functionTo lib.types.attrs;
79-
default = import ./flake-typescript.nix pkgs;
79+
default = import ./typescript/flake-typescript.nix pkgs;
8080
readOnly = true;
81-
description = lib.mdDoc ''
82-
TODO(jaredponn): write down documentation here
83-
'';
84-
example = lib.mdDoc ''
85-
TODO(jaredponn): write down an example here
86-
'';
81+
description = lib.mdDoc builtins.readFile ./typescript/description.md;
82+
# TODO(jaredponn): add an example
83+
# example = lib.mdDoc '' '';
8784
};
8885

8986
};

flake-lang/typescript/description.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<!-- This file is used in `../build.nix`'s `description` for TS -->
2+
3+
<!-- markdownlint-disable MD041 -->
4+
Creates a flake for a TypeScript project.
5+
6+
Returns an attribute set of the form
7+
8+
```nix
9+
{
10+
devShells."${name}-typescript" = derivation { ... };
11+
packages."${name}-typescript" = derivation { ... };
12+
packages."${name}-typescript-tgz" = derivation { ... };
13+
packages."${name}-typescript-node2nix" = derivation { ... };
14+
checks."${name}-typescript-test" = derivation { ... };
15+
}
16+
```
17+
18+
where
19+
20+
- `packages."${name}-typescript"` contains the project with a
21+
`node_modules/` provided by Nix (in the `configurePhase`), and
22+
its `buildPhase` runs `npm run "$npmBuildScript"` (where `npmBuildScript` is
23+
`build` by default).
24+
Indeed, one can overlay the entire derivation (which contains
25+
all its dependencies) to postprocess their project as they
26+
see fit. For example, one may want to generate documentation
27+
instead of building the project, by running:
28+
29+
```nix
30+
packages."${name}-typescript".overrideAttrs (_self: _super: {
31+
npmBuildScript = "docs";
32+
installPhase =
33+
''
34+
mv ./docs "$out"
35+
'';
36+
});
37+
```
38+
39+
where we assume that the `package.json` contains
40+
`scripts.docs = <some-script>` which produces documentation
41+
in the `./docs` folder.
42+
43+
- `devShells."${name}-typescript-test"` provides a developer shell with
44+
the environment variable `NODE_PATH` as the path to the
45+
`node_modules/` produced by Nix, and the command
46+
`${name}-npm-extra-dependencies` which copies the transitive
47+
closure of `npmExtraDependencies` to the folder `./extra-dependencies`.
48+
49+
Moreover, the `shellHook` will:
50+
- create a symbolic link named `node_modules` pointing to
51+
`$NODE_PATH`; and
52+
- executes `${name}-npm-extra-dependencies`.
53+
54+
- `packages."${name}-typescript-tgz"` is `packages."${name}-typescript"` except
55+
runs `npm pack` after the `buildPhase` to create a tarball of the project in
56+
the directory `$out/tarballs/`.
57+
58+
- `packages."${name}-typescript-test"` is `packages."${name}-typescript"`
59+
except it runs `npm test` after the `buildPhase` succeeding only if `npm
60+
test` succeeds.

flake-lang/flake-typescript.nix renamed to flake-lang/typescript/flake-typescript.nix

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -251,7 +251,7 @@ pkgs.lib.makeExtensible
251251
252252
export NODE_PATH=${pkgs.lib.escapeShellArg "${npmPackage}/lib/node_modules/${srcWithNode2nixIfd.args.packageName}/node_modules"}
253253
254-
echo 'Removing existing `node_modules`, and creating a symbolic link to `$NODE_PATH` with name `node_modules`...'
254+
echo 'Removing existing `node_modules`, and creating a symbolic link named `node_modules` pointing to `$NODE_PATH`'
255255
rm -rf node_modules
256256
ln -sf "$NODE_PATH" node_modules
257257

0 commit comments

Comments
 (0)