-
-
Notifications
You must be signed in to change notification settings - Fork 36
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
32 changed files
with
1,248 additions
and
57 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| cache | ||
| api |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| # Build Configuration | ||
|
|
||
| Build and publish related options are configured in `.csproj` file via MSBuild properties. | ||
|
|
||
| | Property | Default | Description | | ||
| |-----------------------------|------------|--------------------------------------------------------------| | ||
| | BootsharpName | bootsharp | Name of the generated JavaScript module. | | ||
| | BootsharpEmbedBinaries | true | Whether to embed binaries to the JavaScript module file. | | ||
| | BootsharpAggressiveTrimming | false | Whether to disable some .NET features to reduce binary size. | | ||
| | BootsharpBundleCommand | npx rollup | The command to bundle generated JavaScrip solution. | | ||
| | BootsharpPublishDirectory | /bin | Directory to publish generated JavaScript module. | | ||
| | BootsharpTypesDirectory | /types | Directory to publish type declarations. | | ||
| | BootsharpBinariesDirectory | /bin | Directory to publish binaries when `EmbedBinaries` disabled. | | ||
| | BootsharpPackageDirectory | / | Directory to publish `package.json` file. | | ||
|
|
||
| Below is an example configuration, which will make Bootsharp name compiled module "backend" (instead of the default "bootsharp"), publish the module under solution directory root (instead of "/bin"), disable binaries embedding and instead publish them under "public/bin" directory one level above the solution root and enable aggressive assembly trimming to reduce build size: | ||
|
|
||
| ```xml | ||
| <Project Sdk="Microsoft.NET.Sdk"> | ||
|
|
||
| <PropertyGroup> | ||
| <TargetFramework>net8.0</TargetFramework> | ||
| <RuntimeIdentifier>browser-wasm</RuntimeIdentifier> | ||
| <BootsharpName>backend</BootsharpName> | ||
| <BootsharpPackageDirectory>$(SolutionDir)</BootsharpPackageDirectory> | ||
| <BootsharpEmbedBinaries>false</BootsharpEmbedBinaries> | ||
| <BootsharpBinariesDirectory>$(SolutionDir)../public/bin</BootsharpBinariesDirectory> | ||
| <BootsharpAggressiveTrimming>true</BootsharpAggressiveTrimming> | ||
| </PropertyGroup> | ||
|
|
||
| <ItemGroup> | ||
| <PackageReference Include="Bootsharp" Version="*-*"/> | ||
| </ItemGroup> | ||
|
|
||
| </Project> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| # Type Declarations | ||
|
|
||
| Bootsharp will automatically generate [type declarations](https://www.typescriptlang.org/docs/handbook/2/type-declarations) for interop APIs when building the solution. The files are emitted under "types" directory of the compiled module package. | ||
|
|
||
| ## Function Declarations | ||
|
|
||
| For the interop methods, function declarations are emitted. | ||
|
|
||
| Exported `[JSInvokable]` methods will have associated function assigned under the declaring type space: | ||
|
|
||
| ```csharp | ||
| public class Foo | ||
| { | ||
| [JSInvokable] | ||
| public static void Bar() { } | ||
| } | ||
| ``` | ||
|
|
||
| — will make following emitted in the declaration file: | ||
|
|
||
| ```ts | ||
| export namespace Foo { | ||
| export function bar(): void; | ||
| } | ||
| ``` | ||
|
|
||
| — which allows consuming the API in JavaScript as follows: | ||
|
|
||
| ```ts | ||
| import { Foo } from "bootsharp"; | ||
|
|
||
| Foo.bar(); | ||
| ``` | ||
|
|
||
| Imported `[JSFunction]` methods will be emitted as properties, which have to be assigned before booting the runtime: | ||
|
|
||
| ::: code-group | ||
|
|
||
| ```csharp [Foo.cs] | ||
| public partial class Foo | ||
| { | ||
| [JSFunction] | ||
| public static partial void Bar(); | ||
| } | ||
| ``` | ||
|
|
||
| ```ts [bindings.d.ts] | ||
| export namespace Foo { | ||
| export let bar: () => void; | ||
| } | ||
| ``` | ||
|
|
||
| ```ts [main.ts] | ||
| import { Foo } from "bootsharp"; | ||
|
|
||
| Foo.bar = () => {}; | ||
| ``` | ||
|
|
||
| ::: | ||
|
|
||
| ## Event Declarations | ||
|
|
||
| `[JSEvent]` methods will be emitted as objects with `subscribe` and `unsubscribe` methods: | ||
|
|
||
| ::: code-group | ||
|
|
||
| ```csharp [Foo.cs] | ||
| public class Foo | ||
| { | ||
| [JSEvent] | ||
| public static partial void OnBar (string payload); | ||
| } | ||
| ``` | ||
|
|
||
| ```ts [bindings.d.ts] | ||
| export namespace Foo { | ||
| export const onBar: Event<[string]>; | ||
| } | ||
| ``` | ||
|
|
||
| ```ts [main.ts] | ||
| import { Foo } from "bootsharp"; | ||
|
|
||
| Foo.onBar.subscribe(pyaload => {}); | ||
| ``` | ||
|
|
||
| ::: | ||
|
|
||
| ## Type Crawling | ||
|
|
||
| Bootsharp will crawl types from the interop signatures and mirror them in the emitted declarations. For example, if you have a custom record with property of another custom record implementing a custom interface, both records and the interface will be emitted: | ||
|
|
||
| ::: code-group | ||
|
|
||
| ```csharp [Foo.cs] | ||
| public interface IFoo { }; | ||
| public record Foo : IFoo; | ||
| public record Bar (Foo foo); | ||
|
|
||
| public partial class Foo | ||
| { | ||
| [JSFunction] | ||
| public static partial Bar GetBar(); | ||
| } | ||
| ``` | ||
|
|
||
| ```ts [bindings.d.ts] | ||
| export interface IFoo {} | ||
| export interface Foo implements IFoo {} | ||
| export interface Bar {foo: Foo;} | ||
|
|
||
| export namespace Foo { | ||
| export function getBar(): Bar; | ||
| } | ||
| ``` | ||
|
|
||
| ::: | ||
|
|
||
| ## Configuring Type Mappings | ||
|
|
||
| You can override which type declaration are generated for associated C# types via `Type` patterns of [emit preferences](/guide/emit-prefs). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # Emit Preferences | ||
|
|
||
| Use `[JSPreferences]` assembly attribute to customize Bootsharp behaviour at build time when the interop code is emitted. It has several properties that takes array of `(pattern, replacement)` strings, which are feed to [Regex.Replace](https://docs.microsoft.com/en-us/dotnet/api/system.text.regularexpressions.regex.replace?view=net-6.0#system-text-regularexpressions-regex-replace(system-string-system-string-system-string)) when emitted associated code. Each consequent pair is tested in order; on first match the result replaces the default. | ||
|
|
||
| ## Space | ||
|
|
||
| By default, all the generated JavaScript binding objects and TypeScript declarations are grouped under corresponding C# namespaces; refer to [namespaces](/guide/namespaces) docs for more info. | ||
|
|
||
| To customize emitted spaces, use `Space` parameter. For example, to make all bindings declared under "Foo.Bar" C# namespace have "Baz" namespace in JavaScript: | ||
|
|
||
| ```cs | ||
| [assembly: JSPreferences( | ||
| Space = ["^Foo\.Bar\.(\S+)", "Baz.$1"] | ||
| )] | ||
| ``` | ||
|
|
||
| The patterns are matched against full type name of declaring C# type when generating JavaScript objects for interop methods and against namespace when generating TypeScript syntax for C# types. Matched type names have the following modifications: | ||
|
|
||
| - interfaces have first character removed | ||
| - generics have parameter spec removed | ||
| - nested type names have `+` replaced with `.` | ||
|
|
||
| ## Type | ||
|
|
||
| Allows customizing generated TypeScript type syntax. The patterns are matched against full C# type names of interop method arguments, return values and object properties. | ||
|
|
||
| ## Event | ||
|
|
||
| Used to customize which C# methods should be transformed into JavaScript events, as well as generated event names. The patterns are matched against C# method names declared under `[JSImport]` interfaces. By default, methods starting with "Notify..." are matched and renamed to "On...". | ||
|
|
||
| ## Function | ||
|
|
||
| Customizes generated JavaScript function names. The patterns are matched against C# interop method names. |
Oops, something went wrong.