CreativeTech Wiki (internal)

Explore

Paid Post Kit

Concepts

The Paid Post Kit is based on Sveltekit and includes a series of implementation specific to our publishing workflow.

The Paid Post Kit lives in a

Github Repository⁠

that can be cloned and used as a starting point for new project.

A preview of the kit is published here:

Login URL: https://tbrand-review.nytimes.com/paidpost/login Post ID: 100000007677798 Password: 3b8abec4-6f80-5e0f-8876-5f88b57a2086

Svelte and Sveltekit

The Kit is based on

Svelte⁠

and

Sveltekit⁠

. Some basic reading about them would be beneficial to understand the Kit organisation.

⁠

Svelte Cybernetically enhanced web apps svelte.dev⁠

⁠

SvelteKit Web development, streamlined kit.svelte.dev⁠

⁠

After considering other options, such as a vanilla setup with a templating engine, React/Preact and Vue, this stack has been chosen for the following reasons.

Easy learning curve for the team, new hires and vendors.

Widespread adoption in the company and in the publishing industry.

Appeal for new hires and vendors, compared to a vanilla stack.

Good developer experience, thanks to

its closeness to traditional HTML, CSS and JavaScript;

built-in scoped styling, state management, conditional rendering.

Pre-compiled and pre-rendered code, to optimise performance.

Pre-render Svelte components introduce some complexity due to the need to write code that can run on the server, not only in the browser. In some cases, we could render only client-side our pages to furthermore simplify the setup.

Folders

The project follows the

Sveltekit conventions⁠

. The main particularity of the Kit is that the src folder contains two nested folders, lib and project where the custom code is organised.

From the root of the project, the following are the main information about the folders organisation.

src

The src folder it’s the main contains all the files of the project. You’ll be working mainly inside of it.

src/lib

The src/lib folder includes files that can be shared by different projects, imported through the $lib alias. Components, styles, actions that are reusable across different paid posts.

Ideally, the files in this folder are never modified during a project’s production. If you find yourself modifying or adding new files, please consider contributing to the main repository.

In reality, if you really need to tweak something in this folder, just go for it! Remember that each paid post has an independent code base.

src/project

The src/project folder includes files that are specific to the project, imported through the $proj alias. Everything is this folder will be heavily modified and you’ll be adding a lot of code to this folder.

For example, in the components/base folder you’ll find some components that are always present in a paid post build. They live there because they will be heavily modified based on the page design.

In the data folder you’ll find two YAML file with the project’s setting and content.

static

The static folder contains all the static assets of the project, specifically media, such as images and videos. It will be copied in the build folder, and uploaded on a Google Cloud Bucket when uploaded in Scoop.

Content

Content is stored as YAML files in src/project/data. These files are imported and made available as JavaScript objects in src/routes/layout.server.js. New files can be added and imported in the same manner.

There are many resources about YAML syntax.

This⁠

is a simple starter.

Yaml files can also be imported directly as JavaScript objects in single component.

Assets

Once the bundle is uploaded in Scoop the assets will be stored in a cloud bucket and their relative URLs in markup replaced. Be sure to edit the file src/project/data/settings.yml to allow the src/lib/scripts/getAssetUrl.js function to construct the correct URLs.

Why is this needed? The Paid Post Translator only processes asset URLs placed in standard markup attributes (for instance, URLs within a data-attribute are not processed). Due to conditional rendering and our complex layouts, this isn't always feasible for us.

To Do: discuss if there is a better alternative to this.

Styles

Styles in Svelte are

scoped at a component level⁠

The Kit uses CSS and SCSS. src/project/components/Example.svelte shows the use of:

CSS Custom Properties, declared in src/project/styles/variables.css and imported globally in src/routes/+page.svelte

SCSS and SCSS mixins imported from src/lib/styles/mixins.scss.

svelte-preprocess allows to automatically

import a file in each components⁠

, removing the necessity of importing the mixins.scss each time it is needed. At the moment is not used to avoid another dependency, and to enforce the independency of each component. But we can consider to to so in the future!

In an

old implementation⁠

I used to declare variables as SCSS variables and convert them in CSS Custom properties, to have the flexibility of both. It’s an overkill most of the times, but we could consider to use it in the future.

Scripts

The Kit heavily relies on JavaScript. Nearly all aspects are dependent on it. It aims to maintain cleanliness, adhering to Svelte's standards for actions and stores, and incorporates type information through JSDoc comments.

Dependencies

Front-end

GSAP

The Kit uses the licensed version of

GSAP⁠

, installed via the gsap-bonus.tgz package in the root folder. To quote Team Greensock, Tween wisely.

fontfaceobserver

⁠

Font Face Observer⁠

is used to detect when the page fonts are loaded and execute functions as a consequence. For

example⁠

, Scrolltrigger is refreshed to recalculate elements position in case of font sizing changes.

TBD: Swiper/Embla ?

App Organisation

This is the general idea of the app organisation. Click on the image to see it entirely.

⁠

Fonts

We mainly use two web fonts providers: Google Fonts (free) and Adobe Fonts (licensed).

When creating a new Web project on Adobe Fonts, please login with the T Brand Studio account to do so, in order to not have live projects connected to your personal account.

⁠

https://fonts.adobe.com/⁠

Username:

tbrandstudioinfo@nytimes.com⁠

/ Password: T!mes2014

If you need to receive a confirmation email very often, ask to be added to the addresses receiving those emails.

Sometimes we are required to embed web fonts. In this case, they can be saved in the static folder.

If the project uses Adobe Fonts, add Adobe Web Project ID to src/project/data/settings.yml . The styles will be automatically imported in src/routes/layout.svelte .

If your project uses Google Fonts, add the required reference in src/routes/layout.svelte.

Versioning

Each paid post build must be versioned in a GitHub repository accessible by the

Creative Tech Team⁠

, named following this pattern:

TBrandCreativeTech-paidpost-[YYYY]-[clientname]

The indication of the year is important as we have recurring clients. When we have more than one project per client per year, we can add a short label to the end of the name to distinguish them. For example:

TBrandCreativeTech-paidpost-[YYYY]-[clientname]-[projectlabel]