@inlang/paraglide-js 1.0.0-prerelease.13 → 1.0.0-prerelease.15

package/README.md

@@ -22,7 +22,12 @@ npx @inlang/paraglide-js@latest init
   <doc-feature title="Typesafety" image="https://cdn.jsdelivr.net/gh/inlang/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/typesafe.png"></doc-feature>
 </doc-features>
 
-… and much more
+### Treeshaking
+
+<doc-figure src="https://cdn.jsdelivr.net/gh/inlang/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/tree-shaking.jpg" alt="An illustration explaining the benefits of treeshaking in software" caption="How Paraglide JS treeshaking works">
+</doc-figure>
+
+Treeshaking gives us superpowers. With it, each page of your app only loads the messages that it actually uses. Incremental loading like this would usually take hours of manual tweaking to get right. With Paraglide-JS you get it for free. Say goodbye to huge bundles.
 
 
 # Getting started
@@ -30,6 +35,7 @@ npx @inlang/paraglide-js@latest init
 ### 1. Initialize paraglide-js
 
 You can initialize paraglide-js by running the following command in your terminal:
+
 ```bash
 npx @inlang/paraglide-js@latest init
 ```
@@ -41,7 +47,7 @@ Having an adapter is only required if you want to use paraglide-js with a framew
 <doc-links>
     <doc-link title="Adapter for Svelte" icon="simple-icons:svelte" href="https://github.com/inlang/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-svelte/example" description="Go to GitHub example"></doc-link>
     <doc-link title="Adapter for SolidJS" icon="tabler:brand-solidjs" href="https://discord.com/channels/897438559458430986/1163823207128776795" description="View progress"></doc-link>
-    <doc-link title="Adapter for NextJS" icon="tabler:brand-nextjs" href="https://github.com/inlang/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-next/example" description="Go to GitHub example"></doc-link>
+    <doc-link title="Adapter for NextJS" icon="tabler:brand-nextjs" href="https://github.com/inlang/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-next" description="Go to GitHub example"></doc-link>
     <doc-link title="Adapter for Vite" icon="tabler:brand-vite" href="https://github.com/inlang/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-vite" description="Go to GitHub"></doc-link>
 </doc-links>
 
@@ -55,9 +61,9 @@ You can customize the `compile` script to your needs. For example, you can add a
 
 ```json
 {
-  "scripts": {
-    "compile": "paraglide-js compile"
-  }
+	"scripts": {
+		"compile": "paraglide-js compile"
+	}
 }
 ```
 
@@ -93,15 +99,16 @@ m.loginHeader({ name: "Samuel" }) // Hallo Samuel, bitte melde dich an, um fortz
 
 Paraglide JS provides five exports in `./paraglide/runtime.js`:
 
-| Variable | Description |
-| --- | --- |
-| `sourceLanguageTag` | The source language tag of the project |
-| `availableLanguageTags` | All language tags of the current project |
-| `languageTag()` | Returns the language tag of the current user |
-| `setLanguageTag()` | Sets the language tag of the current user |
-| `onSetLanguageTag()` | Registers a listener that is called whenever the language tag changes |
+| Variable                | Description                                                           |
+| ----------------------- | --------------------------------------------------------------------- |
+| `sourceLanguageTag`     | The source language tag of the project                                |
+| `availableLanguageTags` | All language tags of the current project                              |
+| `languageTag()`         | Returns the language tag of the current user                          |
+| `setLanguageTag()`      | Sets the language tag of the current user                             |
+| `onSetLanguageTag()`    | Registers a listener that is called whenever the language tag changes |
 
 ## Setting the language
+
 You can set the current language tag by calling `setLanguageTag()`. Any subsequent calls to either `languageTag()` or a message function will return the new language tag.
 
 ```js
@@ -118,6 +125,7 @@ m.hello() // Hello world!
 The language tag is global, so you need to be careful with it on the server to make sure multiple requests don't interfere with each other. That's why we recommend using an adapter for your framework. Adapters integrate with the framework's lifecycle and ensure that the language tag is managed correctly.
 
 ## Reacting to a language change
+
 You can react to a language change by calling `onSetLanguageTag()`. This function is called whenever the language tag changes.
 
 ```js
@@ -125,7 +133,7 @@ import { setLanguageTag, onSetLanguageTag } from "./paraglide/runtime"
 import * as m from "./paraglide/messages"
 
 onSetLanguageTag((newLanguageTag) => {
-  console.log(`The language changed to ${newLanguageTag}`)
+	console.log(`The language changed to ${newLanguageTag}`)
 })
 
 setLanguageTag("de") // The language changed to de
@@ -133,12 +141,14 @@ setLanguageTag("en") // The language changed to en
 ```
 
 There are a few things to know about `onSetLanguageTag()`:
+
 - You can only register one listener. If you register a second listener it will throw an error.
 - It shouldn't be used on the server.
 
 The main use case for `onSetLanguageTag()` is to trigger a rerender of your app's UI when the language changes. Again, if you are using an adapter this is handled for you.
 
 ## Forcing a language
+
 It's common that you need to force a message to be in a certain language, especially on the server. You can do this by passing an options object to the message function as a
 second parameter.
 
@@ -176,12 +186,12 @@ The emitted functions are often referred to as "message functions". By emitting
 
 Inlang Paraglide-JS consists of four main parts:
 
-| Part | Description |
-| --- | --- |
-| **Compiler** | Compiles messages into tree-shakable message functions |
-| **Messages** | The compiled tree-shakable message functions |
-| **Runtime** | A runtime that resolves the language tag of the current user |
-| **Adapter** | (if required) An adapter that adjusts the runtime for different frameworks |
+| Part         | Description                                                                |
+| ------------ | -------------------------------------------------------------------------- |
+| **Compiler** | Compiles messages into tree-shakable message functions                     |
+| **Messages** | The compiled tree-shakable message functions                               |
+| **Runtime**  | A runtime that resolves the language tag of the current user               |
+| **Adapter**  | (if required) An adapter that adjusts the runtime for different frameworks |
 
 ## Compiler
 
@@ -190,6 +200,7 @@ The compiler loads an inlang project and compiles the messages into tree-shakabl
 #### Example
 
 **Input**
+
 ```js
 // messages/en.json
 {
@@ -199,6 +210,7 @@ The compiler loads an inlang project and compiles the messages into tree-shakabl
 ```
 
 **Output**
+
 ```js
 // src/paraglide/messages.js
 
@@ -207,11 +219,11 @@ The compiler loads an inlang project and compiles the messages into tree-shakabl
  * @param {string} params.name
  */
 function hello({ name }) {
-  return `Hello ${name}!`
+	return `Hello ${name}!`
 }
 
 function loginButton() {
-  return "Login"
+	return "Login"
 }
 ```
 
@@ -228,21 +240,19 @@ Three compiled message functions exist in an example project.
 ```js
 // src/paraglide/messages.js
 
-
 export function hello(params) {
-  return `Hello ${params.name}!`
+	return `Hello ${params.name}!`
 }
 
 export function loginButton() {
-  return "Login"
+	return "Login"
 }
 
 export function loginHeader(params) {
-  return `Hello ${params.name}, please login to continue.`
+	return `Hello ${params.name}, please login to continue.`
 }
 ```
 
-
 Only the message `hello` is used in the source code.
 
 ```js
@@ -259,13 +269,12 @@ The bundler tree shakes (removes) `loginButton` and `loginHeader` and only inclu
 // output/index.js
 
 function hello(params) {
-  return `Hello ${params.name}!`
+	return `Hello ${params.name}!`
 }
 
-console.log(hello({ name: "Samuel"}))
+console.log(hello({ name: "Samuel" }))
 ```
 
-
 ## Runtime
 
 View the source of `./paraglide/runtime.js` to find the latest runtime API and documentation.
@@ -277,7 +286,6 @@ Paraglide-JS can be adapted to any framework or environment by calling `setLangu
 1.  `setLanguageTag()` can be used to set a getter function for the language tag. The getter function can be used to resolve server-side language tags or to resolve the language tag from a global state management library like Redux or Vuex.
 2.  `onSetLanguageTag()` can be used to trigger side-effects such as updating the UI, or requesting the site in the new language from the server.
 
-
 # Writing an Adapter
 
 The following example adapts Paraglide-JS to a fictitious metaframework like NextJS, SolidStart, SvelteKit, or Nuxt.
@@ -287,14 +295,10 @@ The goal is to provide a high-level understanding of how to adapt Paraglide-JS t
 1. `setLanguageTag()`: to set the language tag
 2. `onSetLanguageTag()`: to trigger a side-effect when the language changes
 
-
-
-
 ```tsx
 import { setLanguageTag, onSetLanguageTag } from "./paraglide/runtime"
 import { isServer, request, render } from "@example/framework"
 
-
 // On a server, the language tag needs to be resolved on a
 // per-request basis. Hence, we need to pass a getter
 // function () => string to setLanguageTag.
@@ -302,8 +306,8 @@ import { isServer, request, render } from "@example/framework"
 // Most frameworks offer a way to access the current
 // request. In this example, we assume that the language tag
 // is available in the request object.
-if (isServer){
-  setLanguageTag(() => request.languageTag)
+if (isServer) {
+	setLanguageTag(() => request.languageTag)
 }
 // On a client, the language tag could be resolved from
 // the document's html lang tag.
@@ -311,26 +315,24 @@ if (isServer){
 // In addition, we also want to trigger a side-effect
 // to request the site if the language changes.
 else {
-  setLanguageTag(() => document.documentElement.lang)
+	setLanguageTag(() => document.documentElement.lang)
 
-  //! Make sure to call `onSetLanguageTag` after
-  //! the initial language tag has been set to
-  //! avoid an infinite loop.
+	//! Make sure to call `onSetLanguageTag` after
+	//! the initial language tag has been set to
+	//! avoid an infinite loop.
 
-  // route to the page in the new language
-  onSetLanguageTag((newLanguageTag) => {
-     window.location.pathname = `/${newLanguageTag}${window.location.pathname}`
-  })
+	// route to the page in the new language
+	onSetLanguageTag((newLanguageTag) => {
+		window.location.pathname = `/${newLanguageTag}${window.location.pathname}`
+	})
 }
 
 // render the app
-render((page) =>
-  <html lang={request.languageTag}>
-    <body>
-      {page}
-    </body>
-  </html>
-)
+render((page) => (
+	<html lang={request.languageTag}>
+		<body>{page}</body>
+	</html>
+))
 ```
 
 # Community

package/dist/cli/commands/init.d.ts

@@ -1,30 +1,31 @@
 import { Command } from "commander";
 import { type ProjectSettings } from "@inlang/sdk";
+import { Logger } from "../../services/logger/index.js";
 export declare const initCommand: Command;
-export declare const initializeInlangProject: () => Promise<string>;
+export declare const initializeInlangProject: (logger: Logger) => Promise<string>;
 export declare const maybeAddVsCodeExtension: (args: {
     projectPath: string;
-}) => Promise<void>;
-export declare const addParaglideJsToDevDependencies: () => Promise<void>;
+}, logger: Logger) => Promise<void>;
+export declare const addParaglideJsToDevDependencies: (logger: Logger) => Promise<void>;
 export declare const findExistingInlangProjectPath: () => Promise<string | undefined>;
 export declare const existingProjectFlow: (args: {
     existingProjectPath: string;
-}) => Promise<undefined>;
-export declare const createNewProjectFlow: () => Promise<undefined>;
+}, logger: Logger) => Promise<undefined>;
+export declare const createNewProjectFlow: (logger: Logger) => Promise<undefined>;
 export declare const newProjectTemplate: ProjectSettings;
-export declare const checkIfPackageJsonExists: () => Promise<undefined>;
-export declare const checkIfUncommittedChanges: () => Promise<void>;
+export declare const checkIfPackageJsonExists: (logger: Logger) => Promise<undefined>;
+export declare const checkIfUncommittedChanges: (logger: Logger) => Promise<void>;
 export declare const addCompileStepToPackageJSON: (args: {
     projectPath: string;
-}) => Promise<undefined>;
+}, logger: Logger) => Promise<undefined>;
 /**
  * Ensures that the moduleResolution compiler option is set to "bundler" or similar in the tsconfig.json.
  *
  * Otherwise, types defined in `package.exports` are not resolved by TypeScript. Leading to type
  * errors with Paraglide-JS.
  */
-export declare const maybeChangeTsConfigModuleResolution: () => Promise<void>;
+export declare const maybeChangeTsConfigModuleResolution: (logger: Logger) => Promise<void>;
 /**
  * Paraligde JS compiles to JS with JSDoc comments. TypeScript doesn't allow JS files by default.
  */
-export declare const maybeChangeTsConfigAllowJs: () => Promise<void>;
+export declare const maybeChangeTsConfigAllowJs: (logger: Logger) => Promise<void>;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { cli } from "./cli/main.js";
 export { compile } from "./compiler/compile.js";
 export { writeOutput } from "./services/file-handling/write-output.js";
+export { Logger, type LoggerOptions } from "./services/logger/index.js";